In computing, an Application Programming Interface (API) is a technique for obtaining or posting information based on a contract between the sender and receiver. APIs are generally used for:

  1. Integrating with third party services
  2. Providing content to clients (UI or any other client)
  3. Interaction between various services/microservices

Here are a few best practices for developing APIs:

  1. API versioning - add the API version to the URL /api/{version}/users/{id}
  2. Share only the data that the client needs; don’t allow clients to consume data that they don’t need.
  3. Do not leak sensitive data like database table IDs, unmasked SSNs, etc.
  4. Consider using GraphQL to design APIs that are client-driven.

API Design

REST :- It has strict design principles that are widely understood. It separates the concerns of client and server. It creates stateless architectural designs. GraphQL :- GraphQL is a very popular alternative to REST APIs that is currently taking the developer world by storm. You only get the data you asked for. No more, no less. gRPC :- It is generally used for server-to-server communication. It communicates in binary format, which makes it travel faster through the network for serializing, parsing, validation, etc. It uses the HTTP/2 version.

API User Guide

There are a few important things to include in the API user guide:

  • a clear description of what it is and how you use it.
  • Glossary of terms, if necessary
  • Description of endpoints, grouped by capability if there are many
  • Environment variables
  • Authentication Guidance
  • General API flow/walkthrough
  • Examples
  • Error messages

API Gateway

The API gateway is the entry point to access various capabilities of a complex platform via a well-defined API. To illustrate this concept, let’s say we build a website for a movie store and design an API /movies for its homepage. This API, hosted on a single service, returns the list of movies in the store plus recommended movies.

Imagine that the store grows over time and you decide to build specific services for songs and documentaries. Also, you decided to build a dedicated recommended service Thus, to render the homepage, you now have to integrate with multiple microservices, increasing the total number of roundtrips made to the backend. If a new category is added, the whole process of reintegration repeats. An API gateway can absorb this complexity by connecting to the homepage once and orchestrating the requests to as many microservices as needed. Plus, you can independently evolve your microservices without having to change the client integration.

API Management

Some examples of API management platforms:

  • Microsoft APIM
  • Apigee (Google)
  • Mulesoft API Manager
  • AWS API Manager
  • 3-Scale (Redhat)

Generally speaking, an API management platform offers the following capabilities:

  • API gateways – components that proxy traffic from consumers to services that implement APIs. Traffic can be checked for appropriate authorization, throttled, and have transformation performed on message payloads before being sent to the back-end service.
  • Developer portal – a web portal for developers to view documentation on your APIs, download SDKs to develop with, register their applications, and request access to secure APIs
  • API lifecycle management – to manage the development, deployment, publishing, and versioning of APIs
  • API analytics – to receive real-time data about the performance and usage of your APIs
  • API monetisation – to manage service plans, billing, and charging for the use of your APIs

API maturity

This concept describes the level of maturity and effectiveness of your APIs, including their design, documentation, governance, security, performance, and usability. There are various API maturity levels, like:

Accessible:
  • APIs are accessible to other applications.
  • It is designed as part of the product, not just a side effect.
Robust:
  • APIs are supported, stable, and managed.
  • API lifecycle management and versioning
  • Monitoring and Metering
  • Operational Support
  • Health Check Endpoints
Discovery:
  • Discoverable through the search UI and API documented.
  • Published in a marketplace
  • Tagged for searchability
  • User Documentation
  • API Endpoint Documentation
Interactive:
  • Users can experiment to see if it meets their needs
  • Multiple execution environments, including ‘try me’
  • It behaves the way the user expects.
Self-Service:
  • Access without personal interaction with the creator or maintainer
  • Self-Registration
  • Built-in monetization