1 interface name
user/ user/adduser/xxx
is familiar from the name, and the developer who calls the interface and the developer who takes over later can roughly guess the function of the interface based on the interface name.
2 agreements
When designing an interface, the protocol for calling the interface should be specified, whether to use the HTTP protocol, the HTTPS protocol, or the FTP protocol. For example, cross-language calls usually use the WebService protocol.
3 version: v1
For the URL of the interface, the version number should be added.
For example, Gaode map api:
https://webapi.amap.com/maps?v=2.0
4 paths
Since the interface obtains a resource, try to use nouns instead of verbs in the URL
/api/pruduct/v1.0/
/api/users/v1.0
5 actions
For a restful interface, actions can be specified to express the intent of the interface.
- post: new
- put: modify (modified full data)
- patch: modify (which one to modify, which one to pass)
- delete: delete
- get: query.
6 Interface parameter verification
Input and output parameter verification is an essential step when writing a program. The designed interface must first verify the parameters. For example, whether the input parameter is allowed to be empty, and whether the input parameter length meets the expected length. The status returned by the parameter can be given a default value, and the error code and exception information can be specified, instead of throwing the exception directly to the front end or a third-party caller.
7 Scalability
If the interface is similar to public interfaces such as printing logs or recording call information. In addition to being called by the current business, other subsequent businesses or functions may also be called. When designing such an interface, the scalability of subsequent functions should be considered.
8 Interface idempotency
To analyze the business functions of the current interface, it is necessary to consider whether to add idempotence to the business.
For specific implementation, please refer to How to implement interface idempotence
9 Thread Pool Isolation
If all businesses share a thread pool, and some edge businesses have bugs or blockages that cause the thread pool to block, important businesses will be affected. Therefore, the thread pool is isolated, and more core threads are allocated to important businesses to better protect important businesses.
10 Exception and timeout handling
When calling third-party interfaces or distributed remote services, exception handling, interface timeouts, and retry times need to be considered. How to deal with it needs to be analyzed according to the actual business.
11 log printing
Provide to third parties or call third-party interfaces.
Problems often occur due to inconsistencies in call results. Print the call request parameters or return parameters, and quickly troubleshoot problems when they occur.
12 Interface Security
If the interface is provided externally, the security of the interface needs to be ensured.
Use token mechanism instead of username and password.
Encrypt and desensitize private information such as mobile phone number and ID number in the parameters.