Skip to content

Files

Latest commit

chusochuso
Add new interesting links comparing API styles
Dec 12, 2020
5a383bc · Dec 12, 2020

History

History
71 lines (55 loc) · 7.93 KB

apis_introduction.md

File metadata and controls

71 lines (55 loc) · 7.93 KB

Introduction to APIs

Putting it simply, an API, or Application Programming Interface, is a language which allows two systems to talk to each other through the network. We use them constantly, when browsing the Internet or when using a mobile application. For example, they let the Twitter application interact with the Twitter server to read and publish tweets. Some people even say that for a service to be considered an API, it also needs to be reusable.

APIs are so important that many business, like Twilio, are completely based on their API. This leads to very trendy topic: API Management, the process to improve the adoption and engagement of an API.

Paradigms

In addition to providing a good value, API needs to be designed to effectively solve the requirements of their users or customers. This issue is addressed by picking the right API style. In order to classify each API style, let's first introduce some paradigms.

Consumers

Not every API is intended for the same audience:

  • Public APIs: these are publicly available to third-parties. Sometimes, they will require a registration.
  • Private APIs: in contrast, private APIs are only available to services within a company.

Request-response APIs

  • RPC API: this is the simplest form, where the API is designed around arbitrary procedures and typically described using an IDL (Interface Definition Language). There are several existing specifications, like SOAP, JSON-RPC or XML-RPC. Currently, Apache Thrift and gRPC specifications are very popular, both of them containing official implementations.
  • Web API: Or REST. It is an architectural style where the system behavior is based on transitions of data (or resources, as called in HTTP). There is no official implementation.
    • REST-like. A key characteristic of REST is that their clients just follow (or bookmark) opaque URIs. When we use a so-called REST API where clients construct URIs, then it is not pure REST, but RPC over HTTP. This is often referred as REST-Like.
  • Query API: in addition to the styles above, we also have query APIs, like GraphQL. It is essentially an RPC API, exposing a single service, that allow clients to run queries, using a SQL-like syntax, and make changes through mutations. Its state is represented in form of graph.

Event-Driven APIs

Constantly sending requests to a remote API to find out when something happens might be resource-expensive. According to some studies, 1.5% of those API calls returns new data. To prevent this, Event-Driven APIs might be used:

  • Publish-subscribe API: Kafka or AMQP.
  • WebHooks: an application subscribes to a topic, and will receive events through an HTTP endpoint. These subscriptions can be done programmatically (for example, in Microsoft Graph API) or manually (supported for example in GitHub).
  • WebSocket: programmatically, an application subscribes to a topic and will receive events through a websocket. Used by GraphQL subscriptions.
  • HTTP Streaming: very common back in the day, consists in an open HTTP request which allows the API server to sent data back to the client at will. Used, for example, by Twitter.

Resource or action oriented

Very often, we see a clear separation between: resource-oriented and action-oriented APIs:

  • Resource-oriented API. The API is structured around resource identifiers, nouns, and a small set of operation to manipulate them. For example, in a resource-oriented API like REST, to read a user we will use the predefined GET method of HTTP on its identifier. This is very useful because it let API users to follow a well-known pattern. When facing a new API, they will already know how to do most operations, like creating or updating a resource.
  • Action-oriented API. The interface is designed around the actions. RPC fits here, where an arbitrary method is exposed. For example, a custom method getUser(int id) can be created. Given the simple nature of RPC, this style is convenient to express whatever operation an API designer wanted to expose. For example: mergeUsers(int idFrom, int idTo).

There are design proposals to converge both approaches. For example, Google recommends API designers to always follow a resource-oriented style, even in RPC APIs like gRPC, using a predefined set of standard methods: List, Get, Create, Update and Delete. And when an operation does not naturally match any of these, then a custom method can be created.

REST, gRPC and GraphQL

This project is focused on three specific styles of request-response APIs:

  1. a WEB API style: REST, an architectural style with no official implementation that leverages all HTTP capabilities.
  2. an RPC style: gRPC, an implementation with no standard, developed by Google and with support for many languages.
  3. a query API: GraphQL, a framework developed by Facebook that can be used on any programming language.

They have been chosen because of their maturity, adoption and popularity. The Software Architecture and Design InfoQ Trends Report of April 2020, an opinionated report measuring the adoption of trends and technologies, places GraphQL and gRPC as technologies that have already crossed the chasm, reaching to the early majority, whereas REST fits into the late majority category.

Resources