Best Practices for Building a Modern API Stack
Alex Walling is the field CTO at RapidAPI. This article by Alex is about modern API development and the tools, resources, and processes needed to support that.
There are many reasons that APIs have become so important to all industries. This article will focus on the developer gap. There is a lot of investment in digital transformation and innovation. But there are not enough developers to support this type of innovation. This is what we call the developer gap.
So, organizations are forced to use the developers they have as effectively as possible and drive that innovation through their existing services. And finally, as you’re experiencing developer turnover, you need to onboard and provide the right tools and resources to support your developers.
API ecosystems are becoming more complex.
Whether it’s by the nature of the organization and maturing its API strategy or just, over time, as new technologies and resources come into play, it is inherently making our API ecosystems more complex. Traditionally, in the past, it was only REST or SOAP. But now we’re looking at Graph QL, webhooks, web sockets, gRPC, and Kafka. We’re evolving the definition of an API. Previously, it was single cloud providers and data centers. Now, we’re looking at multi-cloud hybrid approaches. Now, there are multiple gateways and vendors in one organization. Multiple teams across locations are collaborating and building their own resources. You need to approach this and provide the resources and processes to support this complex ecosystem.
Modern API developer stack
You need it to support not only REST and SOAP but also the more non-traditional API types like Graph QL, Async APIs, gRPC, and RPC, and this is going to continue to evolve and get more complex. You will need to look at the integration from your client as you test and build the API through to testing and monitoring. You have to design a full build process without having to utilize other tools, ensuring it’s a seamless integration between all the different steps a developer needs to take to build and deploy an API. You also need to integrate with the existing tooling and ensure visibility across the development lifecycle across different teams in the organization, building these APIs.
At RapidAPI, we look at two core personas. These are the developers or API builders who are building, deploying, testing, monitoring, and publishing their APIs, and the API consumers, the developers who are discovering, evaluating, integrating, and monitoring.
API Builder Persona
API design – The first step in any great API is design, taking a product-first mentality, and making sure that you’re starting with that design. There are a lot of tools out there that enable developers to share and collaborate on these APIs, designing and mocking them. It’s important to meet developers where they are with the tools and assets that they’re already using. As it is an iterative approach, think of versioning. As always, collaboration is king. You’ve got a lot of great assets, and being able to combine these is the most important thing to do.
There are many tools and a few different strategies or philosophies on how to design your API. If you have a client-based approach, you’re looking at the request-response model and building out that API spec as you develop the API. You may use a spec-first approach, where it’s pure design, typically more of a code-first approach, creating that open API specification. One of the newer trends we’re seeing is API spec linting, where you not only test and validate API functionality but also enforce certain style guidelines and consistency across the APIs. Ultimately, building APIs that are consistent and easy to use is really difficult, even if you have an experienced team. API spec linting enables organizations to broadly enforce the style guidelines and enforce documentation best practices across the APIs.
Build and Deploy – This fits into the standard deployment model. A developer pushes their code to GitHub, which triggers a build process and will then deploy the back ends. It will publish the spec to the gateway to ensure those are in sync. And then finally deploy to something like an API hub to facilitate that collaboration. But once you deploy that API, it doesn’t end there.
Test and Monitor – API quality is the most important thing you have. These are production services that other internal or external customers utilize. One issue with an API can cause many issues with an application. Because it has added value, this enables you to achieve real CI / CD flow. It’s all automated because you’re testing that API and ensuring it’s working in the different environments you’re deploying. And because it’s easy, APIs are inherently built as great assets to be able to test.
Publish – When you publish APIs, it is very important to define access. All developers, end users, and consumers may not be required to use all APIs. So, setting up that fine-grained access and controlling and managing that API is important. We want to ensure we publish the full API, not just API specs and references. It should have all content that surrounds the API; tutorials, how-to guides, etc.
Finally, make it self-serviceable.
API Consumer Persona
Discovery – Create one single spot for all of your developers to be able to find the API reference documentation, and start using it as quickly as possible while bringing in all of the data and metadata that you have available to make more informed decisions about which APIs to use. Use advanced filtering to search by tag, metadata, categories, etc. Enable users to view API metrics, including uptime, latency, and popularity.
Evaluate – Test the API thoroughly to see if it meets your requirements. For this, provide access to playgrounds, sandboxes, mock-ups, etc.
Integrate – Support integration with SDKs and code snippets. Make it easier to embed APIs into applications. Use examples. It’s not only about the API reference; the tutorials, documentation, and examples are needed to support this better.
Monitor – Monitor these APIs and continue to ensure they perform. This is not only from the builders’ perspective but as an API consumer who can see how this API impacts the application. Provide analytics not only to the builders but also to the consumers.
To summarize, the next generation API developers stack will be –
- Thinking about the entire flow from the builder to the consumer.
- Ensuring that you get the tools developers want to use to support their efficiency better.
- Optimize for openness because developers will always be picky about which tools they want to use. So an open platform will enable you to rotate out tools as needed and support the different development workflows.
- Ensure that you’re supporting multiple different types of APIs
- Be environment agnostic; developers don’t care where the backend API is being deployed; they want to use that functionality so that they can solve the problem they have.
- Keep development tools separate from runtime components. Having the best-in-class developer tooling is important, not just a package bundle of everything under the sun.