Moment For Technology

How do you design a great API

Posted on Dec. 2, 2022, 8:11 p.m. by Sarah Glenn
Category: The back-end Tag: The back-end restful

At present, the backend interface can be developed with RESTFull style, Web Service, SOAP protocol, RPC protocol, and HTTP protocol. You can use either a short or a long connection. If we want to go further, we can also divide it into synchronous or asynchronous, single or batch, SDK package, internal interface or open interface platform, and so on.

Judge the dimension

1. Certain specifications should be defined for API interfaces, such as being short and easy to remember, easy to understand, etc. From the perspective of program, API should follow industry specifications, and no special treatment is required when calling, which is beneficial to reuse existing code or tools.

2. After the API is released, it should be adjusted according to the feedback of real users or the needs of business development. These adjustments must not affect users as much as possible. Either provide support for multiple releases, or provide users with a realistic update strategy, etc.

3. The public API has the risk of being attacked, and the number of visits cannot be accurately estimated. A good API must have anti-injection, tamper-proof, anti-replay and other security mechanisms, and also avoid service failure when the number of visits increases sharply.

URL specification

1. The URI is short and not redundant. Every WEB API is a service, so the "service" in the counter example below is redundant, and the "API" is repeated twice, which is bad for memory and input.

Example: is: the code

2. There is no mixed-case URI. The HTTP protocol (RFC7230) states that except for schemas and host names, all information about URIs is case sensitive. The following two counter examples use mixed case and are not easy to remember.

Example: counterexamples: the code

Uniform URI, ensure that uniform rules and style, easy for users to remember and use, easy to modify URI, naming has predictable rules, the following positive example we can easily guess to change the final ID can access other content information.

Is: the code

Specification summary

1. Uris are best made up of nouns. The full name of a URI is the Uniform Resource Identifier, which is used to identify the location of a Resource on the Internet. It is similar to a mailing address, which is made up of nouns. There are also some things to be careful about when using nouns. First, use the plural form of nouns. Second, try to use the same words used in most apis. Third, by using as few words as possible; Fourth, as far as possible without strange abbreviations, etc.

2. Do not use Spaces or encoded characters, for example, use Chinese characters in URIs.

3. Use hyphens (-) to join multiple words. The spinal method is recommended: First, the host name (domain name) in the URI is case-insensitive and allows hyphen but prohibits underscores. Second, the dot character has a special meaning, in order to be consistent with the rules for host names.

Spine: serpentine: hump method: the code

Version control

1. Version iteration is inevitable in the development process, but how to achieve good compatibility between various versions without breaking the original API to avoid affecting the normal use of the old version, especially when the program is online and not used by many people?

2. You can also recommend the upgrade to the users of the old version who are going to be abandoned. However, it is not recommended to directly close a version or not to maintain a version. (You can refer to the recent Windows announcement on Win7)

3. Good RESTFull will display the specific version number on the URL. The more common solution is to put the version number in the request Header and in the URL, but I recommend using the second solution, which is more intuitive and convenient

Example: *Copy the code

4. There is also an industry specification for version numbering: Semantic Versioning ( The version number consists of three digits connected by a period, for example, 1.2.3, which respectively indicates the major version number, minor version number, and patch version number. The increment of the version number follows the following rules:

  1. Adding a major version number when making a backward incompatible change to the software;

  2. When making backward compatible changes to the software or abolishing certain specific functions, adding the second version number;

  3. If the API of the software has not changed and only some bugs have been fixed, add the patch version number.

Status code

1. When the client sends a request to the server through the API, the client should know the feedback, whether it is a failure, a success, or a request error. An HTTP status code is a set of standardized codes for various possible scenarios for an HTTP request. The server should always return the correct status code.

2. Many people like to put error messages in the return value, typical Code and Message, in fact, is not good, the following is the Http status Code, can be reasonably used to deal with a variety of request feedback, the ERROR of Http itself and the server internal error, have a good distinction.

Interface documentation

1. An old programmer joke. Programmers hate uncommented code and code with comments. Writing documentation is boring, but essential, and good documentation will preserve your sanity and avoid many problems with API consumption. A good document includes a dictionary table of enumeration values, request parameters for all API interfaces, request methods, request paths, return parameters, and correct and wrong examples. Each request parameter and return parameter must be commented, no one should guess, the document must be evolutionary, and the document must be updated synchronously as changes are made.

2. Try not to use automatically generated documents, but if you do, make sure you check and verify the documents. Don't narrow down the content of the request and response. Make some important points bold in your document.

At the end

Today's share here first, if you think it is valuable, please move hands to point out the "share" button, so that more friends can see, I will be more motivated to insist on sharing. In addition, I will share my career planning, job interview, skills improvement, influence building and other experiences in the future. Welcome to pay attention to the "_ I think, therefore I am"!

About (Moment For Technology) is a global community with thousands techies from across the global hang out!Passionate technologists, be it gadget freaks, tech enthusiasts, coders, technopreneurs, or CIOs, you would find them all here.