Enterprise Rails

API Design Best Practices

So far, four principles of service design have been laid out. Now we turn to the API itself, and define four guidelines for an API design that will ensure your application maintains a high level of user-perceived speed. The jump from monolithic application design to service-oriented design is not without trade-offs. In exchange for reduced local complexity and other benefits of a modular SOA design, you give up locality of information. Because the overall architecture no longer features a single application directly connected to a database, overhead is imposed in the form of network messaging between services. This overhead can either be detrimental to performance or it can be barely noticeable if the API is designed to minimize overhead.

Four guidelines described below can help keep the overhead in the “barely noticeable” category. Note that these guidelines may seem contradictory at times. That is why they are guidelines rather than rules. An appropriate balance must be found between each of the guidelines, based on the situation at hand.

Send Everything You Need

In object-oriented programming, it’s a best practice to have lots of small methods that each perform a small function and return a small piece of data. Within an application, method calls are cheap, so writing small methods that are easily testable is often desirable. In a service-oriented architecture, on the other hand, method calls are processed remotely within the service, and therefore any ...