When building cloud applications, you need APIs to expose logic or data that other users, applications, other APIs, or services can use. This is an integral part of a sound microservices architecture and engineering.
Hybrid cloud services that facilitate development and evolution of these service APIs include service API gateways that can limit or control API access, services to secure ingresses to services and APIs, tools and services to document and test APIs, in addition to the ability to meter and charge for APIs.
There are many reasons why a microservices architecture should expose services APIs, including:
APIs open your services to the world. Each service might have multiple APIs that can be exposed.
Enable serverless usage so that customers can pay for what they use. For many companies, there is a desire to pay for the exact cloud resources consumed — while being able to access unlimited cloud resources when scaling is required.
Advanced API features are now available as a service and in many clouds. For instance, specific services enable you to meter the API, to throttle and deal with rapid scale, to secure all endpoints, and to allow retries and other “corner cases” that arises when using an API at scale.
When exposing APIs, there is a common set of tasks and a common high-level architecture. The steps include figuring out what part of the service or application or data that needs to be exposed as a service. This is called API design. The output of this step is an Open API document listing the different endpoints, the methods exposed (i.e., POST, PUT, GET), and the data structures in and out of these methods.
After the design phase, you need to generate the stubs and skeletons for the API document and connect that to the backend code that implements the API methods and consume and return the necessary data structures.
Finally, you need to plan for non-functional attributes for the APIs and deployments. An API Gateway is an excellent means to achieve this last step. Many cloud providers have API Gateways readily available to use. You can alternatively deploy your own. The next sections highlight examples of these depending on the targeted cloud or open source projects you can use if you want to deploy your own.
- Serverless approaches to API consumption is not in scope since we plan to cover the whole topic of serverless as its own guide.
- Scaling applications, services, and APIs, at large scale, is a topic that requires its own treatment. However, basic scaling, which is required by all APIs can be achieved by an API Gateway.
- Securing APIs is in scope, however, there are advanced authentication and security and access control that are outside the scope and best provided as a separate service from the cloud provider or externally.
The following are lists of open source projects that are commonly used in defining, developing, and managing APIs. Different clouds have built-in offerings of these projects and we includes these and tutorials and blogs and videos that are useful for creating APIs in hybrid clouds.
- RESTful web API design
- Best Practices in API Design
- Best Practices for Designing a Pragmatic RESTful API
- Kong Gateway: 3 Steps to Getting Started
- Service Connectivity for Mordern Architecture
- Swagger API documentation tutorial for beginners