An API strategy comes in different shapes and sizes based on the organization and underlying service being delivered. Retrofitting a beautiful REST API on a legacy banking systems involves a radically different set of activities and approach vs. the opportunity for an evolutionary approach from a start-up.
This post will explore the optimal way of approaching system design to easily and effectively enable an external API platform as the business opportunity and client need arises.
API Centric Architecture via Microservices
A key part in this story is the usage of microservices, which, for the sake of this post, are small, highly dynamic, REST-enabled services. This architectural style has become popular for good reasons in terms of both agility and service robustness. The other key benefit is that it forces API-based communication early on, which brings with it the need for discipline in terms of designing and documenting the various endpoints that fulfill the service capabilities.
A microservices architecture is the first step in the right direction to enabling an evolutionary API strategy.
Exposing APIs Internally
Initially, a microservice will exist only to serve traffic internally. That is, to provide support to other microservices vs. external users. A key difference here is the set of capabilities needed to effectively satisfy the consumers’ needs. For example, the minimal set of capabilities required for internal consumption are:
- Documentation - Preferably via a formal specification like the OpenAPI specification along with a just-enough-wiki to get your colleagues going.
- Issue tracker - Somewhere to file issues against the API not functioning as expected or to request new capabilities.
- Community - Slack channel or forum where questions can be asked.
These three items set the base of supported needed to help others consume the APIs. Clearly, there is much more than can be done here but it is a challenge as today it drives up cost, reduces agility and slows time to market. The net is that currently internal developers are treated as second class citizens …. we’ll revisit this!
Exposing APIs Externally
As the business matures and looks to seize opportunities to offer new features to customers there is a need to then externalize more of the underlying APIs. This step offers a point of “graduation” for a microservice where the clientele moves from not only internal calls but also external calls from the scary outside world. The capabilities required to support this advance can look quite different.
A typical strategy in this approach is to just facilitate the external API with a gateway. This gateway handles common tasks associated with API Management (like authentication, rate limiting, plan subscription). The gateway can choose which endpoints and methods to expose and then simply proxies the calls to the backend microservice responsible for the capability.
Above and beyond the internal capabilities documented above the API will need to provide:
- High quality documentation - From the likes of Stripe, OrderCloud.io or Slack. Documentation including overviews, tutorials and references is essential to a successful API.
- SDKs / Client Libraries - As discussed previously, SDKs make the lives of developers substantially easier as they can stay in their native language context and not switch to HTTP/JSON mode. SDKs must also be included in the documentation as developers will gravitate towards this method of API consumption vs. raw HTTP.
- Status - Up / down must be clearly available for the underlying service and exposed in a way that is transparent for consumers. There is nothing more annoying than a service provider obfuscates the real status to try to save face. If you know a provider that does this, it is time to shop around.
The above delineation is a fairly accurate representation of the industry today. However, we have a big opportunity to advance the state-of-the-art such that all microservices can be “external” ready for a very low cost (free?). Furthering the information that can be captured in API specifications, improving SDK generation and simplifying a gateway-per-service topology will be key to achieving this. The end result will be faster time-to-market for new APIs and a consistent experience for internal and external consumers.
Has your organization successfully implemented an evolutionary approach to exposing APIs from microserives? If so, how did you find the experience and what would you do differently next time?