Restful Web APIs:
Concepts :
- Resource: By URL we mean the URL of something, such as a product, user or home page. These URL-named things are called resources.
- Resource representation: After a web browser sends an http request for a resource, the server responds with a document (usually an HTML document, but sometimes a binary image or something). Whatever document is sent by the server, we refer to this document as the representation of the resource.
- Addressability: Each resource should have its own URL.
- Short session: The HTTP session is only maintained during one request, the client sends the request and the server responds.
- Application state: In REST, the particular page we stay on is called the application state.
- Resource status: Various resources are stored in the server, and the status of these resources is called resource status. The GET method does not change the resource state.
- Idempotence: After deleting a resource, the resource disappears. When the delete request is sent again, a response 404 may be received, but the resource status and the first delete
- Consistent after the resource.
HTTP GET method : It means to tell the server "give me the representation of this resource"
HTTP response is divided into 3 parts:
- status code;
- Informed body;
- response header. The important header is Context-Type, which explains to the client how to understand the entity message body, and we call its value the media type of the entity message body. Common types are text/html (for HTML), and image types image/jpeg. application/json: build constraints on ordinary text; application/vnd.collection+json: build constraints on JSON, comply with the constraints of Collection + Json, is a list describing http resources, for example:
{
"collection": {
"href": "http://www.youtypeitwepostit.com/api/"
}
}
curl命令：
curl -H "Context-Type:application/vnd.collection+json" -d "{"template":{"data":[{"prompt":"Text of message","name":"text","value":"squid"}]}}"
HTTP Method:
- GET: Request a representation of a resource and is a secure HTTP method.
- DELETE: deletes a resource, is an unsafe HTTP method.
- POST: 1> POST-to-append Send a POST request to a resource to create a new resource in the next set of that resource. When the client sends a POST-to-append request, it will add the representation information of the resource it wants to create in the entity message body and send it to the server, responding with 201 (created: successfully created) or 202 (Accept: intended to create but not yet create); the POST method is neither safe nor idempotent, for example, if the same POST request is sent, 5 resources with the same content will be created.
- PUT: 1> Modify a resource. Response after successful modification: 200 (OK) or 204 (No Content) status code. 2> If the client knows the URL of the new resource, the PUT method can also be used to create a new resource. The PUT request is also idempotent, that is, sending the same PUT request 10 times is the same as sending it once (even if it is used to create a new resource, it is idempotent. Unlike the POST request, even if the PUT request is sent multiple times, will also only create one resource).
- PATCH: The PATCH method allows the client to modify only a small part of the resource state. Instead of sending the full representation information through a PUT request, you can create a special "diff" representation and use it as the payload of the PATCH request Data is sent to a server. Response: If the server wants to send data to the client (such as a representation that the resource has been updated), then 200 is the best choice; if the server only wants to state that the execution has succeeded, then 204 (No Content) is sufficient. The PATCH method is neither guaranteed to be safe nor idempotent.
- LINK and UNLIKE: Used to manage hypermedia links between resources. Idempotent, but not safe.
- HEAD: A lightweight version of the GET method, the server will process the HEAD method like GET, but does not need to send the entity message body, just send the HTTP status code and header. Replacing GET with this method will not save time (the server still needs to generate all HTTP headers), but it will save bandwidth usage.
- OPTIONS: The return of the request contains an Allow header that shows all the methods supported by this resource. (The method does not understand the PATCH, LINK and UNLINK methods).
A well-designed API will send a hypermedia document in response to a GET request and use this document to advertise the functionality of a resource. The links and forms in these documents clarify the HTTP requests that the client can make next. Poorly designed APIs use human-readable documentation of what kinds of HTTP requests a client can make.
The protocol semantics of HTML documents only support GET and POST methods.
REST system : server, client, cache, proxy, cache proxy, etc.
Common HTML controls allow the server to describe the following 4 types of HTML requests to the client:
- The <a> tag describes a GET request for a specific URL, which will only be generated when the user triggers the control;
- The <img> tag describes a GET request to a specific URL, which will be automatically initiated in the background;
- The <form> tag with the method="POST" attribute describes a POST request to a specific URL, which will have an entity message body constructed by the client. This request will only be made when the user triggers the control.
- The <form> tag with the method="GET" attribute describes a GET request to a custom URL constructed by the client. This request will only be made when the user triggers the control.
HTML Form VS URI Template:
The HTML hypermedia control cannot tell the browser how to create a URL like http://www.youtypeitwepostit.com/search/rest . But another hypermedia technique - URI templates can do it.
URI template: http://www.youtypeitwepostit.com/search/{search }
http://www.youtypeitwepostit.com/message/?query={query }
HTML form:
<form method="GET" action=" http ://www.youtypeitwepostit.com/message/ ">
<input type="text" id="query" name="query" />
<input type="submit" name="Search">
</form>
URIs , URLs, and URNs:
First of all, URI is a uniform resource identifier, a uniform resource identifier, which is used to uniquely identify a resource. The URL is a uniform resource locator, a uniform resource locator, which is a specific URI,
that is, a URL can be used to identify a resource, and also indicates how to locate the resource. And URN, uniform resource name, uniform resource naming, is to identify resources by name, such as mailto:[email protected] .
That is to say, URI is an abstract, high-level concept that defines uniform resource identifiers, while URL and URN are specific resource identifiers. Both URL and URN are a type of URI.
HTTP request : method, target URL, HTTP headers and entity message body