[case20] talk about rest api design

  Api design


This paper mainly studies the design of rest api.

design criteria

  • 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.

Input specification

  • 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.

  • Paging

Such as page and size, or limit and offset

  • Sorting

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.

  • Version

Versioning is not recommended, and a new domain name is recommended to distinguish it from the original api.

Output specification

  • 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.

Safety related

  • 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.