APIs are used to glue web client and servers, or mobile app and its backend, or different backend services within the microservice architecture.
Server listens on a port and respond to the requests that are sent to it, e.g. listen on HTTP port for URL requests, or on RPC port for RPC requests, sometimes both.
The 3 most popular flavors: REST, GraphQL, and RPC
- REST is not a protocol, a file format, or a development framework. It’s a set of design constraints: statelessness, HATEOAS(Hypermedia As The Engine Of Application State), and so on.
- rely on HTTP verbs and organize things as "resources"
- solves over-fetching and under-fetching problem in REST
- easy to change API
- created by Facebook, originally used by mobile app calling backends. Github started to use GraphQL for its API since v4, replacing v3 REST API.
- a completely different protocol distinct from HTTP, however it uses port 80 and 443 to support HTTP proxies.
- full-duplex communication channels over a single TCP connection.
Usually used in microservices, among the backend services.
3 pupular choices: ProtoBuf, Thrift, Avro
- Thrift and ProtoBuf are statically typed, while Avro uses a more dynamic approach
- Protocol Buffers: came from Google, and used by all Google internal services
- Thrift: came from Facebook and used by all Facebook internal services
- Thrift has data serialization and RPC framework in one; ProtoBuf is the data serialization, gRPC(open source) or Stubby(Google's internal) is the RPC framework
- developed by Google. Google internally uses Protocol Buffers as its primary file format.
- language neutral.
- uses HTTP/2 for transport, supports full-duplex streams between client and server. HTTP is NOT exposed to the API designer, gRPC will generate subs and skeletons to hide tHTTP from the client and the server.
- Protocol Buffers is similar to Thrift. It provides a compiler and a set of libraries that a developer can use to serialize data. A developer defines the structure or schema of a dataset in a file and compiles it with the Protocol Buffers compiler, which generates the code that can then be used to easily read or write that data.
- Compared to Thrift, Protocol Buffers support a smaller set of languages. Currently, it supports C++, Java, and Python. In addition, unlike Thrift, which provides tools for both data serialization and building remote services, Protocol Buffers is primarily a data serialization format. It can be used for defining remote services, but it is not tied to any RPC (remote procedure call) protocol.
- Thrift provides a code-generation tool and a set of libraries for serializing data and transmitting it across a network. It abstracts the mechanism for serializing data and transporting it across a network. Thus, it allows an application developer to focus on core application logic, rather than worry about how to serialize data and transmit it reliably and efficiently across a network.
- With Thrift, an application developer defines data types and service interface in a language-neutral interface definition file. The services defined in an interface definition file is provided by a server application and used by a client application. The Thrift compiler compiles this file and generates code that a developer can then use to quickly build client and server applications.
- A Thrift-based server and client can run on the same computer or different computers on a network. Similarly, the server and client application can be developed using the same programming language or different programming languages.
- supports rich data structures, including nested data.
- schema(in JSON) is stored along with data. Therefore, an Avro file can be later read by any application. In addition, since schema is stored along with data, each datum is written without per-value overheads, making serialization fast and compact.
- When data is exchanged over a network using Avro, the sender and receiver exchange schemas during an initial connection handshake.
- Avro automatically handles field addition and removal, and forward and backward compatibility—all without any awareness by an application.
- REST/HTTP: the addressable entities are “data entities” (called “resources” in the HTTP specifications), and the behaviors are hidden behind the data (the verbs like GET, POST, DELETE).
- Remote Procedure Call (RPC): the addressable entities are procedures, and the data is hidden behind the procedures. (However Google is suggesting a resource oriented design even for gRPC: https://cloud.google.com/apis/design/resources)
Both communication ends(clients and servers) must respect communication best practices, to ensure a stable and reliable distributed system.
- servers: report meaningful error status, signal when they run out of capacity
- client: throttle to send fewer requests to capacity restrained servers
The API gateway pattern: every request needs to go through API Gateway in order to consume the underlying APIs.
API Gateways will perform non-business logic functions: auth, logging/telemetry reporting, monitoring, analytics, quota, rate-limiting, security, anti-abuse, routing, load balancing, HTTP to gRPC transcoding, etc.
- Basic API Gateways: API call routing, authentication, authorization, quota enforcement. Examples: Amazon API Gateway, Google Cloud Endpoints(based on NGINX).
- Advanced API Gateways: more features, like custom code, XML and JSON transformation, advanced API management. Examples: Google's Apigee Edge, Salesforce's Mulesoft.
- AWS API Gateway
- GCP Cloud Endpoint
- Azure API Management
- (Google's) Apigee API Gateway
- Kong: Enterprise fully managed, otherwise not fully managed
- Ambassador: based on Envoy, not fully managed
- both open-source
- both describe APIs: OpenAPI describes REST API in a JSON or YAML file, while gRPC uses ProtoBuf
- ALL Google internal APIs are based on gRPC (actually gPRC's predecessor, Stubby)
- Apigee is one of the founding members of OpenAPI, and it was acquired by Google in 2016; gRPC was from Google. So Google actually supports both...
- gRPC is part of Cloud Native Computing Foundation and OpenAPI is part of Linux Foundation
Google's API design decisions: https://aip.dev/
Google's API Style Guide: https://cloud.google.com/apis/design/
- Graphql vs rest: https://medium.freecodecamp.org/rest-apis-are-rest-in-peace-apis-long-live-graphql-d412e559d8e4
- Why do REST APIs suck?: https://about.sourcegraph.com/go/grpc-in-production-alan-shreve