API Publisher/API Lifecycle Manager

When you develop microservices, you design them around business capabilities. You may also integrate multiple microservices and form a composition to build them. If you need to expose this capability as a managed capability to the consumers, you will have to create an API for doing so.

API providers or creators are responsible for designing, developing, publishing, deploying, versioning, governing, monitoring availability, and measuring performance. The API Publisher/Lifecycle Manager component of an API management solution is responsible for this.

The API Publisher or API Lifecycle Manager allows you to develop, document, scale, and version APIs. It also provides API Lifecycle Management-related tasks, such as publishing an API, monetization, analyzing statistics, and promoting.

API Gateway

When you publish an API from the API Publisher, the API definition is pushed into the API gateway component. API gateway secures, protects, manages, and scales API calls. All the requests that the API consumers send are intercepted by the API gateway. It applies policies such as throttling and security, using handlers, publishes data for API observability and other API governance tasks. Also, in certain cases, we may implement composition of multiple business functionalities at the API gateway level. However, you need to be cautious about what type of compositions you do at the API gateway level and must avoid the monolithic gateway antipattern discussed in Chapter 7, “Integrating Microservices”.

Most of the API management solution vendors often call their entire solution an API gateway. You should keep in mind that all the other functionalities of the other components may get baked into a single solution.

API Store/Developer Portal

API Analytics/Observability

API analytics or observability is a critical factor from both the technical and business perspectives. Therefore, API management solutions provide various API analytics capabilities out of the box. This includes metrics on API invocation, API subscribers, top APIs, top developers, slow/fast APIs, API invocation errors, trending APIs, and so on. Also, the ability to trace the API traffic is a critical factor for troubleshooting and identifying bottlenecks. It is also required to have conventional runtime monitoring capabilities and logging. Some other solutions, such API monetization, are built on top of the API analytic data.

API QoS

API Quality of Service (QoS) has multiple perspectives such as security, caching, throttling, and other SLAs (Service Level Agreements). We have two dedicated chapters (Chapter 11, “Microservices Security Fundamentals” and Chapter 12, “Securing Microservices”) covering microservices security fundamentals and we cover API security as part of them. Other QoS aspects, such as caching, throttling, etc. are pretty straightforward to implement with any API management solutions (and they have no special notion in the context of a microservice). Most of the QoS-related enforcements are done at the API gateway level and offload the actual decision making (e.g., security token validation) to an external entity.

API Monetization

APIs are all about your business capabilities and you can generate revenue by exposing them to your customers/partners. API management solutions provide such capabilities out-of-the-box to build a monetary ecosystem around your API management solution.

API Definition with OpenAPI

The key idea of designing an API for a microservice is to hide the implementation details and only expose the interface that addresses a specific business functionality. The OpenAPI specification (OAS), which is formerly known as Swagger, defines a standard programming language-agnostic interface description for REST APIs. It allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic.

OpenAPI documents describe an API’s services and are represented in either YAML or JSON formats. These documents may be produced and served statically or be generated dynamically from an application.

You can either start by designing the API first (contract first) and then implement the API (may be using code-generation plugins) or you can first implement the API and derive the OpenAPI definition for your service. However, it’s important to keep in mind that OpenAPI is not intended to cover all possible styles of RESTful service design. You can learn about building an OpenAPI-based API definition by referring to OpenAPI samples¹.

A Query Language for Your APIs: GraphQL

As discussed in Chapter 3, “Inter-Service Communication,” GraphQL provides a query language for APIs, which are not necessarily based on the REST architecture. We can still implement API management on top of GraphQL-based services and expose them as managed APIs. An API based on GraphQL can be more powerful than a conventional RESTful API, as it provides a complete and understandable description of the data in your API, gives clients the power to ask for exactly what they need and nothing more, makes it easier to evolve APIs over time, and enables powerful developer tools.

API Management and Service Mesh

With this distinction, Figure 10-2 shows how you can use API management along with a service mesh.

The API/edge services that we develop at the API gateway layer serve a specific business functionality. They call the downstream microservices and may contain some business logic that creates compositions/mashups of multiple services. API services also need to call the downstream services in a resilient manner and apply various stability patterns, such as circuit breakers, timeouts, and load balancing/failover. They can offload such functionalities to the service mesh. Therefore, there will be a service mesh sidecar proxy running alongside each API service. (Although most of the API gateway solutions out there have these features built in, they can still offload such functionalities to the service mesh.) Since the service mesh is the network communication infrastructure, and it allows you to decouple and offload most of the application network functions from your service code, you will have a separate control plane to manage such capabilities. There can be certain overlapping features such as observability of a given API service, which is available from both service mesh and API management observability capabilities. We can still keep them as two different things, as the API management layer is designed for business capabilities, while the service mesh layer is designed for non-business logic inter-service communication requirements. Another important difference is that the API management layer only manages your API services, while the service mesh control plane manages all your service instances.

There are some API management solutions that support both API management and service mesh management from the same layer/component. For example, Apigee and Istio support a similar architecture pattern. With Apigee support for Istio integration, the user can expose one or more services from an Istio mesh as APIs by adding API management capabilities via Istio’s native configuration mechanism. Apigee APIM publishes the API policies etc. via the Istio mixer and application of such policies are done at each sidecar. With this approach, we no longer use the API micro gateways but everything is offloaded to sidecar proxies. API token validation, throttling can be managed via APIM UI. This pattern is relatively new and yet to be battle-tested with real-world production use cases.

Implementing API Management

Implementation of comprehensive API management for your microservices requires catering all the API management aspects that we discussed earlier. There are quite a few solutions, which have drastically cut down the API management features and promote them as an API gateway for microservices. You need to be cautious when selecting an API management solution and make sure you can facilitate all your API management requirements. Also, if you have fully embraced a container-native architecture, the components such as API gateway must be container-native too (i.e., they must support a micro-gateway architecture).

There are quite a few API management solutions out there, such as Apigee, WSO2 API Manager, Kong, MuleSoft, etc. We don’t focus on comparing and contrasting them or recommending a specific solution. We want to give full freedom to the readers to evaluate them and select the most suitable technology. You can find couple of API Management use cases built with such API Management solutions in the samples of chapter 10.

Event Notifications

Event notification is a common form of EDA where a service sends events to notify other services of a change in its domain. Often the event receiver must have the autonomy to carry out the task, if it wishes to do so. An event needs not carry much data on it; often a reference to where the updated information can be retrieved is sufficient.

For example, as shown in Figure 10-3, suppose we have two microservices, called Customer and Shipping. When there is a change in customer information, such as a customer’s address, we can send an event notification to the Shipping service. The event itself may not have all the details of the change, but includes a reference to where the information related to the change can be obtained. As discussed in Chapter 3, the asynchronous event-based communication can be used to realize such scenarios; we can use queue-based communication or topic-based communication to do this.

Obviously, most of the message/event broker solutions can be used as the backbone to implement this pattern and Kafka, RabbitMQ, and ActiveMQ are most commonly used in this domain.

It is an anti-pattern to have logic flow that runs as part of event notifications. For example, if your event publisher expects the receivers to do a certain tasks upcon the receipt of your event. then there is a logic flow between the event publisher and receiver. Some of the mere theoretical microservices books and other resources suggest that every integration/composition of microservices must be done using asynchronous event-driven communication. That literally means having logic flows across your microservices that run via event notifications.

Having these kinds of logic flows is not a practical approach because they are extremely hard to manage and troubleshoot. Maybe the only way that you can derive such a logic flow is via observability (tracing). Therefore, you need to be cautious when applying an event-notification pattern to a scenario where you need to pass commands (you expect the receiver would do a definite task upon the receipt of your event).

Event-Carried State Transfer

This is a subtle variation of the event notification pattern. When an event is trigged, the subscribers are notified with events that contain details of the data that changed. So, the recipient services don’t need to access or refer to any other systems or services. The data is already being received as part of the event. Figure 10-4 shows the same scenario that we discussed in the previous section, which is now modified with an event-carried state transfer.

One of the possible downsides of this approach is the duplication of data across multiple services, because all the subscribers will receive the same data. The implementation technology can be similar to event notifications. On the flip side, there is also decreased network traffic, because in this approach, the shipping service would not need to make a request to the customer service to get the updated address.

Event Sourcing

By using asynchronous messaging techniques, we can persist each state-changing event of an entity as a sequence of events. All such events are stored in an event bus or event log and subscribers can derive the state of that entity by processing the sequence of events that has taken place on that entity. For example, as shown in Figure 10-5, the Order Processing service publishes the changes taken place on the Order entity as events. The state-changing events such as order created, updated, paid, shipped, etc. are published to the event bus. With event sourcing, since we have all the state changing events in the event log, multiple consumers can materialize different view of the same data and those consumers can discard the application state completely and rebuild it by re-running the events from the event log on an empty application. Also, we can determine the application state at any point in time as the events are recorded sequentially. If we need to replay the events executed previously (maybe with some modifications to those events), we can also do that using the event log.

The subscriber applications and services can recreate the status of an order by just replaying the events that are taking place on an order. For example, it can retrieve all the events related to order 11234 and derive the current state of the order.

Command Query Responsibility Segregation (CQRS)

Most of the conventional services or applications are developed with the assumption that we create new records, read records, update existing records, and delete records when we’re done with them. These are known as CRUD (Create, Read, Update, and Delete) operations and all these operations are executed on top of a common model. This approach is known as the CRUD model.

However, with the microservices and modern sophisticated enterprise requirements having a common data model for all, such operations are not always feasible. For example, suppose that you have two functionalities of a given service, one to search and read records from the table and the other one to update records in the table. In most cases, these two functionalities are drastically different and using a common data model often complicates the implementation. In such cases, we can split the common data model into a query model and a command model. This is the fundamental concept behind CQRS.

In CQRS (see Figure 10-6), the query model is primarily used for reading data from the datastore, while the command model is used for managing records in the datastore.

These models may operate on the same database but often have dedicated databases with significant advantages. If we assume that we use two dedicated databases for each model, then we need some sort of event-driven messaging mechanism to keep the data in sync. In most cases, eventual consistency (we discuss this in detail in Chapter 5) is sufficient for CQRS scenarios, hence the event-driven messaging techniques that we discussed earlier can be used to build CQRS.

In the context of microservices, we can consider that each query and command model are part of two different microservices. Since they have dedicated databases and well-defined functionalities, they are adhering to most of the microservice data management techniques. The complete decoupling of query and command model allows us to use two completely different persistent layers (databases) for command and query services. For example, we can use a database that is optimized for reads in the query model while we use a write-optimized database for command model. While CQRS has several advantages, such as independent scaling and management of read and write components of your application, we should use it when it is absolutely necessary to have the separation between the command and query models, because it comes with added complexity related to synchronizing the same data across multiple datastores/caches. For most commons use cases, the CRUD model fits elegantly.

Stream Processing

The software components that receive and send data streams and execute the business logic are called stream processors. Unlike conventional event-driven architecture, the processing logic of a stream is written against not one event but across multiple.

In the context of microservices, some of the input to your microservice can come from streams or microservices, which have to publish to a given stream. Therefore, the ability to integrate stream processing along with your service is a common requirement.

Programmatic Stream Processing

Stream processing can be done by writing code to process events sequentially from a source event stream. As shown in Figure 10-7, an actor or agent that accepts an event, processes the event and produces new events. A stream processor allows you to write logic for each actor, which takes care of most of the heavy lifting tasks such as collecting data, delivering to each actor, ordering, results collection, scaling, and error handling.

There are quite a few stream processor solutions out there, including Apache Storm², Apache Flink³, and Kafka Streams⁴, and they are based on a coding approach to stream processing.