When organizing API endpoints, they should be based on the resources instead of on actions. The request methods will determine what action should be taken at a given URL endpoint. Your entire API’s scheme should be consistent, clear and concise.
API的终点究竟是什么?
In simple terms, an API endpoint is the point of entry in a communication channel when two systems are interacting. It refers to touchpoints of the communication between an API and a server. The endpoint can be viewed as the means from which the API can access the resources they need from a server to perform their tasks. An API endpoint is basically a fancy word for a URL of a server or service.
APIs operate through ‘request’ and ‘response’. And when an API requests to access data from a web application or server, a response is always sent back. The location where the APIs sends a request and where the response emanates is what is knowns as an endpoint. Reputedly, the endpoint is the most crucial part of the API documentation since it is what the developer will implement to make their requests.
An API refers to a set of protocols and tools that allow interaction between two different applications. In simple terms, it is a technical that enables third-party vendors to write programs that can easily interface with each other. On the other hand, an endpoint is the place of interaction between applications. API refers to the whole set of protocols that allows communication between two systems while an endpoint is a URL that enables the API to gain access to resources on a server.
API 终端点优势
- Should be intuitive
- Organize by resource
- Use nouns in the path, not verbs
- The method used will determine the operation taken
- GOOD:
- https://example.com/posts
- BAD:
- https://example.com/get_posts
- Keep a consistent scheme
- Plural nouns for collections
- Use parameters to specify a specific item
- GOOD:
- https://example.com/entrees
- https://example.com/entrees/5
- BAD:
- https://example.com/entree
- https://example.com/entree_five
- Don’t make them too complex or lengthy
- No longer than
collection/item/collection - GOOD:
- https://example.com/entrees/5/reviews
- BAD:
- https://example.com/entrees/5/customers/4/reviews
- No longer than
| Resource | GET | POST | PATCH | DELETE |
|---|---|---|---|---|
| /tasks | Get all tasks | Create a new task | Partial update of all tasks | Delete al tasks |
| /tasks/1 | Get the details of task 1 | 错误! 因为背面有它 | Partial update of task 1 | Delete task 1 |
| /tasks/1/notes | Get all the notes for task 1 | Create a new note for task 1 | Partial update of all notes of task 1 | Delete all notes of task 1 |