1, what is the restful style of apirest, that is representational state Transfer, can be understood as "
Representation State Transformation (of resources)”。
On the network, we enter the URL through the browser to access and obtain the required resources. The URL here is a description of the location of the resource, which is actually
how a resource is presented in a specific way, which is what we call the "presentation layer". The process of accessing resources involves changes in data and state,"
based on the presentation layer (URL) to change the state of the resources ", that is," presentation Layer State Transformation (REST). "
the rest specification API, known as the RESTful API, plain English A little bit, allows us to "
understand its role through API interface name ", it is elegant, normative, easy to understand, save a lot of meaningless communication and documentation. What is the core specification? Use four different request methods in the HTTP protocol to represent four different verb actions: get is used to get resources, post is used to create new resources, put is used to update resources, and delete is used to delete resources.
Specifically,The
RESTful API has the following features：
- Based on "Resources", data and services, everything is a resource in restful design.
- Each URL represents a resource
- URL semantics are clear, there are no verbs, only nouns (verbs are represented by request)
- Use HTTP POST, DELETE, PUT, GET to indicate additions and deletions to the resource
- Try to use JSON instead of XML
- The version number of the API should be placed in the URL
For example, an API provides a zoo(Zoo)System-relatedinformation, the RESTful API style is as follows:
- Https://api.example.com/v1/zoos
- Https://api.example.com/v1/animals
- Https://api.example.com/v1/employees
A little more specific:
- Get/zoos: List all Zoos
- Post/zoos: Create a new zoo
- GET/ZOOS/ID: Get information about a given zoo
- PUT/ZOOS/ID: Update information for a given zoo
- Get/zoos/id/animals: List all animals in a designated zoo
- DELETE/ZOOS/ID/ANIMALS/ID: Delete a designated animal from a designated zoo
API can also provide some parameters to filter the return results, the common parameters are as follows:
- ? limit=10: Specifies the number of records returned
- OFFSET=10: Specifies the start position of the returned record.
- ? page=2&per_page=100: Specifies the number of pages, and how many records per page.
- ? SORTBY=NAME&ORDER=ASC: Specifies which property The returned result is sorted by, and the sort order.
- ? Animal_type_id=1: Specifying Filter criteria
Here is a vivid example of the Watercress book-related development API:
First look at this link, what is the role? Try direct access (get mode), what is the return content? https://api.douban.com/v2/book/1220563 2, restful when to usefor the Open API, watercress, Sina Weibo, GitHub, useful, very suitable for internal development, not good.
The resource-based RESTful API interface granularity and return results are too coarse, and it usually returns a complete data model, which is very unfriendly to the client. But the open API is open because it does not know what you need to return the results, and since you do not know, then I will simply return to you. This benefit is generic, but the client is not good at handling. You only need a field, the server is dropped to you more than 10, as a client developer what do you think?
Internal development due to the very clear requirements, generally speaking, the server should not be simple and rude to directly throw the resource entity to the client. Can't the restful API be plugged into in-house development? Of course not, we need to be flexible and learn from the benefits of restful to design our internal API. So how to simplify, you need to ponder and experience.
3. Reference links
- Rest and restful API best practices
- Understanding the RESTful architecture
- RESTful API Design Guide
- What I think of as restful API best practices
[01] Talking about the RESTful style API
