In distributed systems, service-oriented design is an important factor in creating a robust, scaleable, consistent, and high-available system architectures. But this is easier said than done.
The importance of designing service API’s that specifically meets the needs of system functionality, scaleability and reliability, and performance goals often gets diluted as services are, often times, easy to identify as a component.
But what does it mean to define a service API that truly is well-defined and well-designed?
In order to answer this, we need to understand what a service API is, and what characteristics provide a well-defined and well-designed API.
Note: This is not a post on SOA (service-oriented architecture). There are principles of SOA that are represented in my service-oriented design, such as loose-coupling, statelessness, reusability, service abstraction, and more, but architecture is not the focus of my post.
A service API provides a contract or interface that both clients and the service agree and adhere to. Therefore, the client does not need to know how the service does its job of servicing a request. The client only needs to know the details of the contract necessary to make a successful service request call.
Service API Design
Service API design requires some thought as to the details of how best to provide an API that both satisfies the client, and respects the constraints and goals of the system architecture as it pertains to service-oriented design.
In distributed systems, some common goals of a good service-oriented design are to support a system architecture that is
- consistent, and
Now let’s discuss some general factors that can help guide us in making good design decisions. They are
- Iteration speed
- Logical functionality
- Read/write frequency
- Join frequency
Understanding how each service relates to these factors is a great first start in the service-oriented design process because you will begin to fit your services into the overall system architecture by key architectural characteristics required of modern distributed, scaleable, and robust systems.
Keep in mind that some tricky, but important, trade-offs may be necessary at times. Taking the time to understand how each of these affects your overall design goals now is time well spent. Changes later down the timeline are always much more painful and costly.
Service API Design is not about being pure REST!
Understanding Your Options Designing an API for use over HTTP
Designing a Service API
Properly designing an API is much like designing other software components. Start with designing the behavior you know about now, and only add complexity when absolutely necessary. Many times, you are balancing defining a well-understood API with lessening the required trips to the service (server) based on client domain data need.
Client domain data need is simply the data the client needs to satisfy a contextual need, commonly the user interface, based on business logic, a.k.a., domain(s).
For example, if looking at a browser screen, this can be a user profile, a list of product orders only, and/or a list of product orders AND their respective line items (think master-detail). All of these require some API design thought as to how the client should request the data, e.g., atomic or multi-record, and how the data should be returned, e.g., atomic or multi-model.
For master-detail relationships, returning both models can reduce trips to the server, but may be heavy to compute server-side.
More coming soon!