This paper mainly studies the design of rest api.
- easy to use & hard to misuse
Ease of use is not easy to misuse, that is, api design should not be too complicated, it should be simple and easy to use, and it should not be easy to use wrong.
- least astonishment
Simple is good, don’t try to provide other fancy and gorgeous additional functions, such as specifying an input format for string parameters with similar time, and don’t try to be compatible with multiple input formats at the same time.
- use case & document story
Api documents should be organized around story or use case to provide complete closed-loop operations in a business scenario.
- Path in url
Avoid humps, underline and cross bars are preferred.
- request method
Post indicates new (
There is no id in the url.), delete means delete, get means query, put means full update (
Idempotent operation), the id carried in the post url can also be used to indicate the update.
Such as page and size, or limit and offset
For example, sort=+field2,-field2 separates multiple sort fields with commas, with+indicating ascending order and-indicating descending order
- Field filtering
For example fields=field1,field2,field3
- Complex query
Simply use eq to represent, for example, lt for less than, lte for less than or equal to, gt for greater than, gte for greater than or equal to, like for fuzzy query; For more complicated words, please refer to the rsql specification.
Versioning is not recommended, and a new domain name is recommended to distinguish it from the original api.
- Return code
Follow the http return code specification, 4xx indicates a client error and 5xx indicates a server error.
- Returns jsonObject instead of jsonArray
If the top-level structure returns jsonArray, it is not easy to expand. Generally returns jsonObject, and usually carries code, error, etc.
- Returns the field of jsonObject
Success indicates whether the request was successful, data indicates data, msg indicates message description, and error describes details of error information.
- Error message format
Type indicates the type of error exception, code indicates the error number is used to personalize the error prompt, msg is used to describe the error information, and link provides the specific description page of the error information.
- Caller authentication
For consumers of api, the appId and appKey are required to be provided when calling, which is used for authentication of the most basic calling source.
- Fine-grained authentication
For finer-grained data permission control, it should be refined to url and requestMethod
- Parameter check
Basic verification shall be performed for parameters such as query and modification, and illegal parameter filtering shall be performed for parameter contents.
- Mask error stack
Do not expose the error stack at the back end. If it is convenient to troubleshoot the problem, you can set a switch to set whether to mask the error stack or not.
- Sensitive data desensitization
For sensitive data, some desensitization should be done properly, such as ID card number, mobile phone number, etc. If you really need real data, you need to make additional requests.
- The account password needs to be encrypted.
The login interface must use https, and must have a graphic verification code, but also must prevent violent cracking, there is an error locking mechanism, for password transmission, must be encrypted
- Prevent id traversal problem
For url parameters, if the id is increasing, traversal needs to be handled, either the processed id is exposed to the outside, or data permission control is done
- Prevent token replay
There must be a certain invalidation mechanism for token, and token is also recommended to sign url parameters.
- Prevent file download directory traversal
For interfaces that provide file download, directory traversal must be avoided
Service quality assurance
- Provide slas
- Provide flow management, fusing and current limiting
- Provide service expansion mechanism
- Provide troubleshooting drills
- Provide audit function
- Monitor abnormal traffic
- Provides isolation between callers
The design of rest api involves many aspects. For the time being, this article only lists some first and needs to be supplemented later.