HTTP Methods and RESTful Service API design

Meaning:

• http Methods: Also known as HTTP Verbs,http Methods can be translated into the HTTP method . They are part of the HTTP protocol, which mainly specifies how HTTP requests and operates resources on the server, often get,post, and so on.
• API:application Programming Interface application interface, RESTful API, such API is via HTTP protocol URL The form is exposed to other system or module calls, such as an API that gets all comments from the user, like this: https://api.server-name.com/user-id/comments

There are nine HTTP Methods, each of which is Get,head,post,put,delete,trace,options,connect,patch

In RESTful API design, post,get,put,patch and delete are commonly used, which correspond to the creation, acquisition, modification, partial modification and deletion of resources.

Purpose and return value conventions for methods

| HTTP Methods | Operation mode (CRUD) | Get multiple resources (/books) return results | Get a single resource (/BOOKS/ID) return results

| POST| Create data Create| 201 (Created) <br/> HTTP Header ' location ' value set to/BOOKS/ID, where ID is the newly created book ID | 404 (Not Found), <br/> If the resource already exists, return to 409 (Conflict) | | GET| Reading data READ |200 (OK) <br/> Returns all books in the body, you can use parameters to get some books data such as /books?page=3| (OK) <br/> Returns the corresponding ID in the body book<br/><br/>404 (not Found) <br/> If there is no corresponding data, or ID is not in the wrong format | | PUT| modifying data UPdate <br/><br/> Entire modification <br/> Modify all properties except ID |404 (not Found) <br/> Unless the API is to implement batch or all updates can return 200, Otherwise generally directly return 404 can |200 (OK) <br/> 204 (no Content) <br/> 404 (Not Found), if the ID format is incorrect or not found | | PATCH| modifying data Update <br/><br/> section modify <br/> Modify part of a record's properties |404 (not Found) <br/> Unless the API is to implement batch or all updates can return 200, otherwise the general direct return 404 |200 (OK) <br/> 204 (no Content) <br/> 404 (Not Found), if ID format is incorrect or not found | | delete|Delete data Delete| 404 (not Found) <br/> generally directly returns 404 unless you really want to delete all the collections to return to a total of |200 (OK)
404 (not Found) if the ID format is incorrect or not found |

HTTP Methods Using detailed instructions POST 　　APIs that use POST are typically used to represent the creation of a single piece of data. For example, if you want to design a back-end database to add an API about library information, you can design: https://api.servers.com/books

• Client invocation: The client puts the data to be created in the body of the HTTP request, such as the body data is {title: "Is Your lights on", Author: "Donald C. Gause"} sends an HTTP POST please To findhttps://api.server.com/books
• Service-Side implementation
  • When the server receives the data from the client post, it finds that books data should be created based on the post URL.
  • After getting the contents of the body to create a new book record and Save, if everything is OK, return 201 indicates the creation is successful.
  • The HTTP Header ' location ' value is set to Https://api.server.com/books/new-created-book-id when returned
  • The client can obtain the Unique ID of the data that was just created, making it easier to use when further action is required

Note: The POST API is not a data security and idempotent operation, and if the client calls the same API multiple times it causes multiple data to be created, the data is the same except for the IDs of the other properties.

Example:

　　POST Https://api.server.com/books

　　POST https://api.server.com/books/123456/comments

GET

Generally used to read data, that is, to obtain resources. A successful call to the GET API returns the corresponding data. If the requested data does not exist to return to 404 (not Found) or because the parameter is incorrect, you can return to the (Bad request)

• Client invoke: The client simply sends an HTTP GET request to the appropriate URL, the request URL can be taken with the relevant parameters to filter the data, such as:GET https://api.server.com/books?author= Gause
• Server-side implementation: After receiving the corresponding request, the server determines what type of data should be returned according to the URL, and filters the data according to the URL parameters and returns it to the client after it is placed in the Body. Get can return a collection, like an array of forms. Such as:

　　

If the client requests only one piece of dataGET https://api.server.com/books/000，应该返回对应ID的数据即可：

Note: A get operation is a data security and idempotent operation, which means that multiple calls to get should return the same data (without modifying the operation) and will not cause any destructive modification of the data.

API Examples:

　　GET https://api.server.com/books/123456
　　GET https://api.server.com/books/123456/comments
　　GET https://api.server.com/books/123456/comments/id001
　　GET https://api.server.com/books?author=gause PUT: Typically used to update records, unlike patches, PUT is typically used to replace all properties of the record. Patches are only part of the update. Unlike post, PUT does not generate a new resource ID, and post generates and returns the newly created data ID

client Invoke : The POST is called almost the same way, such as the data to be modified is the {id: "book-id-000", title: "Are your lights on", author: "Donald C. Gause"} client sends the HTTP PUT request to https://api.server.com/books . Unlike post, the operation takes the UID of the data, which is used to locate the data to be modified to facilitate subsequent operations. Also some design will put the ID in the URL https://api.server.com/books/book-id-000 , so that the data in the body to be modified can not contain the ID

　　server-side implementation : If the update is successful the PUT API should return 200. Returns 204 if no information is returned in the body of the PUT request, or 404 if the ID is not found or the ID is malformed. Unlike post, the API does not have to be updated in the header to just create the data ID URL, because we are modifying that data before its ID has been acquired by the customer.

Note: The put operation is not data-safe because this operation changes the data, but the put operation is idempotent, and for the same put request, the result of the data modification is always the same as the first time, regardless of how many times the call is made.
API Examples: 　　PUT https://api.server.com/books/123456
    PUT https://api.server.com/books/123456/comments/id001 PATCH: PATCH operation only updates part of the data, such as having such a piece of data{id:000, title: "Is Your lights on", Author: "Donald c. Gause", Pub: "XYZ"}PATCH operation may just modify the title, or modify the pub, the content of the specific modified by B Ody data format rules. The body data in the PUT API is typically to replace all attributes of the data (except for the ID). Client calls :　　Unlike put, which is just the body data format, the body of the put request is generally the case
　　　　{title: "Are your lights on"}contains only part of the data to be modified Server -side implementation : The server side of the Body according to the content of the data are partially updated. The successful update data should return 200 when the data ID is not found to return 404. 　　Note: Patch operations are not actually idempotent or data-safe, patch requests from different clients may overwrite and conflict data part propertiesAPI Example: Patch https://api.server.com/books/123456 patch https://api.server.com/books/123456/comments/id001 Delete: Deletes a piece of data, should return 200 after the correct deletion, if the resource ID to be deleted does not exist then return 404,delete is idempotent in the HTTP protocol semantics, no matter how many times after the call, the data is the same deleted state. API Example: Delete https://api.server.com/books/123456 Delete https://api.server.com/books/123456/comments/id001



　　

HTTP Methods and RESTful Service API design