Hello, I’m BitTorrent. Currently our lives are closely surrounded by a large number of Internet services, and there are tens of billions of API calls on the Internet every day.API is a way for two devices to communicate with each other, and every time people move their fingertips on their cell phones, there is an API interface call behind it.

This article lists some common API interfaces and describes the advantages, disadvantages, and relationships between them.

I. API Types

There are many common types of APIs, but this article focuses on API interfaces above HTTP (generalization). Other application layer protocols above the TCP transport layer, such as MQTT, are outside the scope of this article.

1.1 SOAP

The SOAP protocol is based on XML and is used in financial services and payment gateways where security and reliability are critical, and is better suited for scenarios with high levels of data security.

1.2 RESTful

JSON-based lightweight web services, but also the most widely used API protocol.

1.3 gRPC

High-performance microservices communication protocol, which is a microservices architecture favorite.

1.4 GraphQL

A client-side dynamically customizable API protocol, which is not only an API communication method, but also a query language.

1.5 WebSocket

WebSocket is a common means of real-time communication, based on the HTTP protocol. on real-time, bi-directional and persistent connections. If you only need a real-time push from the server, you can also try SSE (Server-sent events), which is also based on HTTP.

1.6 Webhook

Customized remote callback functions, often used for automated processing. We’ve used them when automating the deployment of Jenkins:Ten minutes to get Jenkins+Gitlab+Docker front and back end deployment

Below we will detail the three most commonly used API interfaces: RESTful, GraphQL, and gRPC.

Second, RESTful details

RESTful APIs have a wide range of applications in the mobile Internet era because they are light enough (JSON-based) and very flexible.

REST API specifies a number of standards, such as: unified interface, communication methods, statelessness, cacheability, etc.. APIs that follow the REST API standard are called Restful APIs, and in order to guarantee the maintainability of the API interface, there is usually a version number like v1/v2/v3 at the beginning.

Note that the URL’s resources are named by nouns, not verbs, as you might name them, for example:

https://example.com/api/v3/products

And no:

https://example.com/api/v3/getALLproducts

This is where a lot of unstandardized “RESTful APIs” make the most mistakes, as REST APIs specify that actions are performed using URIs.

HTTP request header type corresponding to the action shown in the table below, is what we often say: CRUD add, delete, change and check:

typology	movements
POST	CREATE
GET	READ
PUT	UPDATE
DELETE	DELETE

The meanings of common HTTP return codes are shown in the table below:

numerical value	in the end
200	successes
400	Request Error
500	backstage error

In addition, we should also pay attention to the idempotency of the API interface. Only in the POST create operation is not idempotent, we have to pay attention to the client’s multiple requests, resulting in data duplication problems.

GraphQL in Detail

GraphQL is an interface protocol developed by Meta, currently used by Github, Shopify, Ins, etc. The most important feature is its flexibility and efficiency. The biggest feature is flexibility and high efficiency, which provides a good choice for products with complex data requirements.GraphQL has many similarities with the RESTful APIs we just mentioned, such as they are all based on http, they all use URLs to locate unified resources, and the data transfer is in JSON format. However, the unique advantage of GraphQL is that the client can customize the content returned by the interface, which greatly improves the dynamic scalability of the program.

If we need multiple combinations of data for an action, then in RESTful API, we may face multiple requests. But in GraphQL it is possible to customize the data in the request header and GraphQL will organize the data for return.

However, it has some drawbacks, one of which is that it is not easy to cache; GraphQL has a single entry point and uses HTTP POST by default, which prevents HTTP caching from being fully utilized. On the other hand, the ability to customize data at will can be dangerous.

IV. gRPC Details

RPC should not be unfamiliar, Remote Procedure Call Remote Procedure Call. That is to say, two servers A, B, an application deployed on the A server, want to call the application on the B server to provide methods. Because it is not in a memory space, it can not be called directly, you need to express the semantics of the call through the network and convey the call data.

gRPC is an open source Remote Procedure Call framework created by Google in 2016 that rewrote and open sourced their overdue internal RPC infrastructure. gRPC is a popular implementation of RPC, and many organizations have adopted gPRC as the preferred RPC implementation solution. There are also frameworks such as Openfeign and Dubbo that can be used as RPC implementations.
At the core of the gRPC ecosystem is the use of Protocal Buffers (protocol buffers) as its data exchange format. It is a language- and platform-independent mechanism for encoding structured data.

gRPC uses Protocal Buffers to encode and send data over the wire. While gRPC can also be encoded in JSON, Protocal Buffers offers several advantages that make it the preferred encoding format for gRPC. Communication between microservices is done by defining a communication protocol proto file, and tools can be used to automatically generate implementations in different languages once the proto has been written:

The Protocol Buffers communication scheme is the key to gRPC’s superb performance. It is a very efficient binary encoding format, much faster than JSON.

Another reason for high efficiency is that gRPC is built on top of HTTP/2 to provide a high-performance foundation at scale. gRPC uses HTTP/2 Stream, which allows multiple streams of messages to be sent over a single, long-term TCP connection. gRPC uses HTTP/2 Stream, which allows multiple streams of messages to be sent over a single, long-term TCP connection. gRPC can be configured to use HTTP/2 Stream. gRPC can also be configured to use Openfeign’s HTTP/2 Stream, which is the most powerful and efficient way to send messages to a large number of people. Of course, Openfeign can also be configured to use HTTP/2.

gRPC is very efficient and 5 times faster than JSON due to binary encoding and network optimization. The following figure shows the process of gRPC communication:

With all the benefits of gRPC, why hasn’t the server used the gRPC protocol when communicating with the client? This is because gRPC relies on access to lower levels of HTTP/2 natively, and no browsers currently support the level of network request control required by gRPC clients.
However, it is now possible to make gRPC calls from the browser with the help of a proxy. This technology is called gRPC-Web, but the feature set is not fully compatible with gRPC. However, it is actually in use on mobile and makes a lot of sense in power and bandwidth constrained environments.

V. API Optimization

• Using caching, you can employ a tool like Redis to cache data to provide efficient communication.
• Connection pooling, using multiplexing techniques, is used to minimize access to the database.
• Avoid N+1 queries, and when an interface requires more than one SQL statement, try to combine them.
• Use paging to reduce the cost of data communication in exchange for faster loading.
• Using JSON, lightweight JSON communication can be balanced between server-side and client-side.
• Compression, data can be compressed using the Brotli algorithm, and many CDNs (Content Delivery Networks) can also support compression.
• Asynchronous logging, when there is high concurrency, this type of work can be distributed to other microservices.

VI. Summary

In this article, we understand the HTTP application layer protocol based on the above, commonly used six API interfaces: RESTful, GraphQL, gRPC, WebSocket, Webhook. each has its own distinctive features and application scenarios, we should be based on the product as well as the team’s specific situation before choosing to use.There is no best API interface, only the most suitable scenario and application.