These days most organizations are providing APIs as part of their digital solutions. Doing so has many benefits, such as the ability to expose data to many types of clients like web applications, mobile apps, and connections with business partners. A microservices approach is usually adopted to enable small code bases built by many separate teams.

Yet microservice architectures must be designed carefully, with an early focus on the difficult areas. Since APIs are managed by many teams, there will be different technologies in use, and not all team members will understand technical best practices. Therefore, a security-first design is recommended since effective API security is difficult to retrofit later on.

Insufficient planning can lead to the type of API sprawl shown below, where there are few rules for how APIs interact. This can cause microservice developers to write too much homegrown code in difficult areas like security, resulting in complexity and potential vulnerabilities. As APIs are composed together during end-to-end flows, there may also be reliability problems that hinder architectural scalability. These factors can result in an uncertain time to market for future business objectives.

A future-facing microservices design is required to avoid these hidden costs. Such a design must address three major areas: deployment, security, and observability. APIs also need to be designed with code simplicity and extensibility in mind. In this post, I will describe a security-first approach for reducing API sprawl based on a separation of concerns philosophy.

Addressing API Sprawl

1. Start with Deployment

The best microservice architectures separate concerns across components. This leads to simpler API code and, thus, more predictable business delivery. Include an API gateway as a hosting best practice so that API servers are not exposed directly to the internet. Also include components that externalize the challenging areas of security and observability from API code. These supporting components usually need to be customizable so that end-to-end API flows can be built later with the desired technical behaviors.

Such components will then be deployed through a CI/CD pipeline with environments such as development, test, staging, and production. Yet an often overlooked area of deployment is the developer setup. If it takes a long time for developers to run an API on their local computer, connect to supporting components, or understand the code, it can lead to business delays. Therefore, encourage excellent developer setups, and monitor them for productivity problems.

2. Avoid Security Vulnerabilities

It is common for team members at organizations to have an incomplete understanding of security best practices, which can cause them to develop incorrect solutions. This can result in failed penetration tests that delay business deliverables. Therefore, aim to set up API security development in a way that avoids vulnerabilities and scales to many microservices.

The most complete security solution for APIs is to use the OAuth 2.0 authorization framework. An authorization server becomes the most central security component to externalize lower-level complexity from API code. Architects design JWT access token payloads to contain claims that restrict client privileges. All APIs should verify the access token and use claims-based authorization on every request.

The best security design patterns require insight. In the above diagram, the API gateway uses plugins to perform utility security jobs to deal with cookies from browser-based clients, confidential opaque tokens from mobile clients, and client certificates from business partners. Yet, in all cases, APIs only need to work with JWTs and claims, resulting in simpler security code that remains business focused.

From an API sprawl viewpoint, this is an effective way to consolidate and modernize security. It is also an excellent way to promote a shared understanding of application security best practices since many team members will already have some OAuth understanding. For some recommendations on how end-to-end API security flows should function, see the article on implementing zero-trust APIs.

3. Ensure Observability

To tame API sprawl, the organization should ensure that the activity of both APIs and supporting components are understood. These days there is some pretty good tooling, along with newer standards such as OpenTelemetry. These enable teams to report activity with very little code. Doing so provides visibility into how an organization’s APIs are being used.

Observability enables an end-to-end view into usage. The ability to support the distributed system effectively and quickly resolve problems is usually worth investing in. Encouraging teams to rehearse failures and then resolve incidents can be an exercise that saves time for the business when such incidents occur in production.

In the above diagram, the second microservice call fails during a multiple API workflow, which could occur for various reasons, such as a temporary network problem. If the user retries, this should not create a duplicate order. Meanwhile, support staff should be able to determine the technical reasons for the failure. Meeting these requirements requires an API strategy with further design and implementation work.

4. Improve API Best Practices

For a real organization, various roles should be consulted. These include business stakeholders, who will be concerned about technical costs, and compliance teams, who will have their own requirements. Reviewing existing APIs could be the responsibility of a platform engineer or architect. This initial work only involves writing documents, so it is not a costly operation.

There are likely to be additional API design questions to consider. This might include REST standards for operations such as filtering so that all of an organization’s APIs feel the same to clients. Minimizing API versioning may also be important since running old and new versions of the same API is usually expensive.

Once the organization has a better technical vision for dealing with complex areas such as API security best practices, they are better positioned to produce a useful inventory of all existing APIs. Such an inventory could include information like each API’s business functionality, the team that owns each API, and ratings for existing deployment, security, and observability.

To get people to adopt best practices, a useful approach is simply evangelizing the desired technical behaviors. Teams are often located in different regions and may use different API technology stacks, so best practice implementations may differ. Allowing choice usually works better than using a top-down governance approach. However, developers are attracted to modern separated design patterns, so adopting this style will improve staff satisfaction.

For future API-related work, often initiated by a business requirement, the newer API practices should be followed when practical. The cost of work also needs to be traded off against business priorities. These technical improvements will take time and require investigation, but the effort will improve the sense of direction.

Conclusion

API sprawl usually arises when microservice responsibilities lack clarity in difficult areas like security. This can be caused by a suboptimal deployment setup or a lack of technical best practices. It is common for API security code to grow in complexity as the number of client connections grows. Thus, leaders should respond to API sprawl using modern tools and technical designs to externalize lower-level concerns and make API delivery more predictable.

By following a security-first approach in APIs and using the type of separation inherent in the OAuth authorization framework, an organization can provide a more scalable microservices architecture. This requires supporting components for APIs, though, so choose them carefully, to ensure they enable the preferred end-to-end API flows. For details on how to get started with this type of API architecture, see the identity and access management primer.