API Design 304: API Design for Microservices

Learn some best practices for designing APIs that will function optimally in microservice architectures

Microservice architecture is helping an increasing number of organizations to minimize the time required for software application projects and to maximize the reliability of backend systems. In this lesson, we explain why APIs are essential to microservices and provide some best practices for designing APIs that will function optimally in microservice architectures.

Microservice architecture is revolutionizing the way enterprises build their technical infrastructure and develop new applications. It was a key factor in the success of various Web-native businesses and is quickly spreading to more established enterprises, especially those currently focused on innovation, the application economy and digital transformation.

With a microservice architecture, monolithic applications are eschewed in favour of lightweight microservices, each delivering a focused set of functions. New systems and applications can be quickly composed by combining functionality from a collection of services. Reliability is increased by limiting the impact failure of any given service will have.

So for example, at the most basic level, the architecture for a microservice-based ecommerce Web site might look something like this:

In this way, microservices present an effective solution to the problem many large enterprises encounter balancing speed and safety in their IT systems. As a company grows, it will typically find this problem more and more challenging but a microservice architecture provides a fast, safe foundation that can scale smoothly as the size and complexity of the system increases.

The Role of APIs in Microservices For a microservice architecture to function, the infrastructure’s components must be able to interact. Each individual microservice must be able to communicate with every other microservice in the architecture as well as with the applications and Web sites they power and the databases from which they draw real-time information, essential to their functioning.

Therefore, each one must have an interface, which is why the Web API is a vital enabler of microservices. Being based on the open networking principles of the Web, RESTful APIs provide the most logical model for building interfaces between the various components of a microservice architecture

So, the role of APIs in the ecommerce infrastructure outlined above might, in part, look something like this:

Best Practices for Designing Microservice APIs The design of microservice APIs should reflect the kind of core architectural practices outlined in Lesson 101: API Design Basics and Lesson 201: Web Architectural Styles. However, there are some specific design practices that should be kept in mind when creating APIs for use in a microservice architecture.

Specifically, microservice API design should reflect best practices for coding microservices themselves. When creating microservices, it is vital to ensure that components are loosely coupled, minimizing dependencies so that any given service can run independently. This will maximize uptime for applications that leverage the services and reinforce the overall system.

There are two key design characteristics that APIs should exhibit to work effectively in a loosely-coupled microservice architecture. Microservice APIs should be:

• Message-oriented
• Hypermedia-driven

Message-Oriented APIs for Safe Refactoring In a microservice architecture, it is vital that any given service can be updated in a way that does not affect its ability to work with the other components of the system. Likewise, it is essential for the APIs that connect these components to be designed with safe refactoring in mind. The most effective way to address this need is by taking a message-oriented approach.

Conventionally, designers of Web services and APIs have taken an object-oriented approach―viewing these interfaces as ways to transmit serialized “objects†over the wire. However, a more efficient approach is to look at any complex system as a collection of services exchanging data via messages.

Adopting this kind of message-oriented approach to API design makes it possible to expose general entry points into a component and receive task-specific messages at the same time―ensuring loose coupling of data and allowing for changes in message content as a way of refactoring components safely over time.

Hypermedia APIs for Maximum Evolvability The message-oriented approach to designing microservice APIs uses loose coupling of data to increase evolvability, making it safer to refactor APIs over time. To truly maximize evolvability, this message-oriented approach should be taken to the next level by designing hypermedia-driven API implementations.

With hypermedia APIs, the messages passed between components contain more than just data. They also include descriptions of possible actions. This means that actions as well as data are loosely coupled. Therefore, taking a hypermedia-driven approach to API design is essential to maximizing loose coupling in a microservice architecture.

The hypermedia style is still fairly new and―as we pointed out in Lesson 201: Web API Architectural Styles―there is a lack of mature tooling and support for hypermedia APIs, leading many developers to view them as excessively complex. Given all this and hypermedia’s importance to microservice APIs, it is worth providing greater insight into the style at this point.

Hypermedia API design is based on the way HTML works in a Web browser―HTTP messages are transmitted, containing data and actions encoded in HTML format. So, in much the same way that you use links to navigate the Web and forms to provide input, a Hypermedia API provides links to navigate a workflow and template input to request information.

Because hypermedia API messages contain both data and actions, they dynamically guide client services and applications by responding not just with static data but also with control metadata that provides guidance on the actions that can be executed with the API. These actions are known as “API affordancesâ€.

Currently, most Web APIs do not describe affordances. To put this it context, it is the machine-to-machine equivalent of a Web page not providing any menus or other hyperlinks to enable navigation but instead requiring you to consult separate documentation in order to determine other URLs on the site that you may find useful or interesting.

To put it another way, when you enter a URL into a Web browser, you get a response including data (text, images) and hypermedia (links). Most APIs respond with data but no hypermedia. Clearly then, the machine-to-machine Web (APIs) is lagging behind the machine-to-human equivalent (Web sites) in terms of usability.

In addition to its impact on usability, this state of affairs also has serious ramifications for evolvability. Again, a comparison to the human-centric Web illustrates this nicely—imagine if you had to have the correct documentation for the latest version of a Web site in order to make effective use of that site.

The hypermedia orientation of the human Web has ensured that it is versioning-free and therefore highly evolvable. From a technical perspective, this is central to the Web’s extraordinary success in scaling and evolving over the last two decades, by providing a consistent and user-friendly experience.

Like Web sites, microservices benefit from being based on a collaborative, highly-decentralized architecture. Conventional, data-only design approaches are too brittle to succeed in such a highly-distributed environment. So, whatever the challenges, a message-oriented, hypermedia-driven approach is preferable for microservice API design.