Design beautiful web APIs
- Don't get too caught up in the term REST.
- Minimize the frequency of API version updates, paying attention to backward compatibility.
- Embeds the major version number of the API version in the URI.
- When the API service is stopped, it cannot be terminated immediately, and it needs to continue to be exposed for at least 6 months.
- Maximize the use of HTTP protocol specifications and minimize the use of private specifications.
- Use the appropriate status code .
- Returns the appropriate, as generic as possible media type.
- Returns information that facilitates the client to perform appropriate caching.
- Use JSON or a data format that is consistent with the purpose.
- Don't do unnecessary encapsulation.
- Response data should use a flat structure as much as possible.
- The names of individual data should be concise and easy to understand, using singular and plural numbers appropriately.
- The error format should be uniform so that the client can mechanically understand the details of the error
- Design endpoints that are easy to remember and functional at a glance.
- Use the appropriate HTTP method.
- Choose the appropriate English word, paying attention to the singular and plural forms of the word.
- Authentication using OAuth 2.0.
Specific operation
Every resource in one or more services you are building has at least one URI that uniquely identifies it. It is best when the URI is reasonable and adequately describes (succinctly, clearly hierarchically) the resource.
Rule #1: URIs should not contain a trailing forward slash (/)
Rule #2: The forward slash delimiter (/) must be used to denote hierarchical relationships
Rule #3: Hyphens (-) should be used to improve URI readability
Rule #4: Underscores (_) should not be used in URIs
Rule #5: Lowercase letters should be preferred in URI paths
Rule #6: File extensions should not be included in URIs
Rule #7: To describe your resources, use specific names instead of action verbs.
Rule #8: Should endpoint names be singular or plural? plural
changing factors
- Our service changes , and the API of the interface obviously changes with it.
- Consider whether it will be used by third parties and whether changing the design of the API will affect the design of third parties.
- Upgrading the api will not affect users who are using the api
- The Web API uses the same HTTP protocol as the Web site, so it will face the same security issues as the Web site, and the specific security issues of the API need to be considered.
- Bad Web APIs are a sign of bad
Version Information Management API
1- Multiple versions of the API can be provided at the same time. The old version uses the previous interface, and the new version uses the new interface
test version
http://localhost:4200/#/newapi/home
http://localhost:4200/#/home
the remaining
Old URI
http://api.example.com/users/123
New URI
http://newapi.example.com/users/123
2- Embed the API version number at the beginning of the URI path
The design of newapi is unreasonable, because the api will be updated at any time
Introduce version number -v2
http://api.tumblr.com/v2/blog/good.tumblr.com/info
old version
http://www.davidslog.com/api/read
3- Terminate the operational cost of providing API
services , security issues , updates to back-end functions (such as database schema changes)
In order to reduce maintenance burden, API version should be updated as infrequently as possible
Considering the security risks ( such as personal information being sent directly without encryption, being able to obtain other people's information, etc. ), and considering the cost, it is unrealistic . In this case, you need to consider options. The appropriate time to deprecate the old version of the API.
Therefore, when terminating API services, especially when terminating those APIs that have been widely used, we need
to announce the expected termination time and other information in advance, so that users can take countermeasures before that. This project is very complex, but it is very important to expose and operate the API.