A client accessing HTTP service forms an HTTP request. HTTP requests are built in three parts, the request line, header variables and request body. The request line has the HTTP VERB: GET, POST, PUT, etc, the requested URI, and the protocol version. The header variables contain key-value pairs. Some of these are standards such as user agent, which helps the receiver identify the requesting software agent. Metadata about the message format or preferred message formats is also included here for HTTPS based rest services. You can add custom headers here. The request body contains data to be sent to the server and is only relevant for HTTP commands that send data such as POST and PUT. Here, we see two examples of HTTP client text-based messages. The first example shows an HTTP GET request to the URL using HTTP version 1.1. There's one request header variable named host with the value pets.drehnstrom.com. The second example shows an HTTP POST request to the URL slash add using HTTP version 1.1. There are three request header variables: host, content-type set to JSON, content length set to 35 bytes. There is the request body, which has the JSON document name Noir, breed, Schnoodle. This is the representation of the part being added. As part of a request, the HTTP VERB tells the server the action to be performed on a resource. HTTP as a protocol provides nine VERBS, but usually only the four listed here are used in rest. GET is used to retrieve resources. POST is used to request the creation of a new resource. The service then creates the resource and usually returns the unique ID generated for the new resource to the client. PUT is used to create a new resource or make a change to an existing resource. PUT request should be idempotent, which means that no matter how many times the request is made by the client to a service, the effects on the resource are always exactly the same. Finally, a DELETE request is used to remove a resource. HTTP services return responses in a standard format defined by HTTP. These HTTP responses are built in three parts, the response line, header variables and response body. The response line has the HTTP version and a response code. The response codes are broken on boundaries around the hundreds. The 200 range means, okay. For example, 200 is okay, 201 means a resource has been created. The 400 range means the client request is in error. For example, 403 means forbidden due to request or not having permission, 404 means requested resource not found. The 500 range means the server encountered an error and cannot process the request. For example, 500 is internal server error, 503 is not available usually because the server is overloaded. The response header is a set of key value pairs such as content-type, which indicates to the receiver the type of the content the response body contains. The response body has the resource representation requested in the format specified in the content-type header and can be JSON, XML, HTML, etc. The guidelines listed here focus on achieving consistency on the API. Singular nouns should be used for individual resources and plural nouns for collections or sets. For an example, consider the following URI/pet. Then a GET request for URI/pet/1 should fetch a pet with ID 1, whereas GET/pets should fetch all the pets. Do not use URIs such as GET/GETpets. The URI should refer to the resource, not the action on the resource. That is the role of the VERB. Remember that URIs are case insensitive and that they include version information. It is a good practice to diagram services. This diagram shows that there is a service that provides access to the resource known as pets. The representation of the resource is the pet. When a request is made for the resource via the service, one or more representations of a pet are returned.
