Essential for developers: API design


This paper mainly discusses the characteristics of RPC and restful API styles and how to select the technology in the development, intercepts some online communities, and provides readers with ideas and views on API design for reference.

1. Background

API scientific name: application programming interface

For example, people communicate with each other through language, while programs communicate with each other through API.

At present, the mainstream API design in the market includes RPC, restful, graphql and other design ideas. There are different opinions on the advantages and disadvantages of API style, but objectively speaking, RPC has the oldest qualification and is still in use today. Restful is the latecomer and has been popular for a long time. It is said that the latest graphql will be put into use in the next version of githup. The choice of API is no less than the fierce struggle between flutter and RN. But the author insists that: there is no silver bullet in software development, technology will eventually be coerced by history and constantly promoted, but for developers, there may be no eternal silver bullet, but it is very important to choose the technology suitable for their own business scenarios at present.

This article mainly discusses the advantages and disadvantages of the first two kinds of API design, in order to provide reference for readers to make technical decisions.

2. RPC takes verb as the core

2.1 naming style

RPC API is usually a verb object structure


Due to the personalized requirements of the interface, when adding new functions, the API may introduce other verbs or prepositions, such as by, with, create, etc., which is also the main reason why restful asks for RPC

  • One is that it is ugly
  • Second, it is not universal enough (after the server is updated, the client also needs to read the document to adapt to the server)

3.1 common practice

  • Interface oriented programming

    In the process of parameter passing, the interface is used instead of the implementation class, which makes the program more flexible and extensible

    For example, use map instead of HashMap, treemap, list instead of ArrayList, LinkedList

  • Method overload

    Generally speaking, the method name is omitted, which makes API calling more convenient

3. Restful takes nouns as its core

“Expressive state transition”

3.1 naming style

/Admin / users (query users) 
/ admin / Users (new users) 
/Admin / users (update users) 
/Admin / users

Although it’s a bit inappropriate, restful’s noun centered API style actually replaces verbs with request methods. The so-called declarative state transition actually blocks part of the API implementation with request methods. But it is undeniable that the readability of the API has been significantly improved.

@RequestMapping(value = "/user", method = RequestMethod.GET)
 @RequestMapping(value = "/user", method = RequestMethod.DELETE)

However, restful can’t adapt to the complexity of API. For example, it is difficult to abstract resources with restful style in common login and registration functions. Restful can upgrade the API by adding, deleting, modifying and querying a single resource. However, due to its coarse interface grain, it is difficult to design a reasonable API for multi resource query operation.

three . 2. Common practice

  • Plural resource name

    Don’t confuse the singular with the plural. For simplicity, use the plural only for all resources.

  • Avoid multi level URLs (controversial)

    Get a certain type of articles of a certain author
    GET /authors/12/categories/2
    GET /authors/12?categories=2
    Query published articles
    GET /articles/published
    GET /articles?published=true

4. How to make technical decisions on RPC and restful?

  • Readability

    Compared with RPC, restful API is more readable and easier to understand

  • compatibility

    Restful is more granular than RPC interface.

    Restful is suitable for adding, deleting, modifying and querying API, while RPC is suitable for more refined and customizable business scenarios

Restful has a better performance in the implementation of development interface API.

In the implementation of business system, RPC has higher customization ability.

5. Some discussions on API interface design
























Reference article

How to design API

Restful and RPC style

Rest and restful API best practices

Thinking about the best practice of API design

Restful API best practices