GET Responses
200 (OK) The method has successfully returned the resource.
204 (No Content) The response body doesn’t contain any content, such as when a search request returns no matches in the HTTP response.
404 (Not Found) The requested resource can’t be found.
GET Request
A GET request retrieves a representation of the resource at the specified URI. The body of the response message contains the details of the requested resource.
A GET request should return one of the following HTTP status codes:
200, 204, 404
POST Requests
A POST request should create a resource. The server assigns a URI for the new resource and returns that URI to the client.
For POST requests, a client shouldn’t attempt to create its own URI. The client should submit the request to the URI of the collection, and the server should assign a URI to the new resource. If a client attempts to create its own URI and issues a POST request to a specific URI, the server returns HTTP status code 400 (BAD REQUEST) to indicate that the method isn’t supported.
POST Request - Data Submission
In a RESTful model, POST requests are used to add a new resource to the collection that the URI identifies. However, a POST request can also be used to submit data for processing to an existing resource, without the creation of any new resource.
Post Responses
A POST request should return one of the following HTTP status codes:
200 (OK) The method has done some processing but doesn’t create a new resource. The result of the operation might be included in the response body.
201 (Created) The resource was created successfully. The URI of the new resource is included in the Location header of the response. The response body contains a representation of the resource.
204 (No Content) The response body contains no content.
400 (Bad Request) The client has placed invalid data in the request. The response body can contain more information about the error or a link to a URI that provides more details.
405 (Method Not Allowed) The client has attempted to make a POST request to a URI that doesn’t support POST requests.
PUT Request
A PUT request should update an existing resource if it exists or, in some cases, create a new resource if it doesn’t exist. To make a PUT request:
The client specifies the URI for the resource and includes a request body that contains a complete representation of the resource.
The client makes the request.
If a resource that has this URI already exists, it’s replaced. Otherwise, a new resource is created, if the route supports it.
PUT Requests - Indempotent
PUT requests must be idempotent, which means that submitting the same request multiple times always results in the same resource being modified with the same values. If a client resends a PUT request, the results should remain unchanged. In contrast, POST and PATCH requests aren’t guaranteed to be idempotent.
PUT Responses
200 (OK) The resource was updated successfully.
201 (Created) The resource was created successfully. The response body might contain a representation of the resource.
204 (No Content) The resource was updated successfully, but the response body doesn’t contain any content.
409 (Conflict) The request couldn’t be completed because of a conflict with the current state of the resource.
PATCH Requests
A PATCH request performs a partial update to an existing resource. The client specifies the URI for the resource. The request body specifies a set of changes to apply to the resource. This method can be more efficient than using PUT requests because the client only sends the changes and not the entire representation of the resource.
{
“name”:”gizmo”,
“category”:”widgets”,
“color”:”blue”,
“price”:10
}
Pathched with
{
“price”:12,
“color”:null,
“size”:”small”
}
This merge patch tells the server to update price, delete color, and add size. The values for name and category aren’t modified.
PATCH Response Codes
200 (OK) The resource was updated successfully.
400 (Bad Request) Malformed patch document.
409 (Conflict) The patch document is valid, but the changes can’t be applied to the resource in its current state.
415 (Unsupported Media Type) The patch document format isn’t supported.
DELETE Requests
A DELETE request removes the resource at the specified URI.
DELETE Response Types
204 (NO CONTENT) The resource was deleted successfully. The process has been successfully handled and the response body contains no further information.
404 (NOT FOUND) The resource doesn’t exist.
Asynchronous response
Sometimes a POST, PUT, PATCH, or DELETE method might require processing that takes time to complete. If you wait for completion before you send a response to the client, it might cause unacceptable latency. In this scenario, consider making the method asynchronous. An asynchronous method should return HTTP status code 202 (Accepted) to indicate that the request was accepted for processing but is incomplete.
Expose an endpoint that returns the status of an asynchronous request so that the client can monitor the status by polling the status endpoint. Include the URI of the status endpoint in the Location header of the 202 response.
HTTP/1.1 202 Accepted
Location: /api/status/12345
If the client sends a GET request to this endpoint, the response should contain the current status of the request.
If the asynchronous operation creates a new resource, the status endpoint should return status code 303 (See Other) after the operation completes. In the 303 response, include a Location header that gives the URI of the new resource:
HTTP/1.1 303 See Other
Location: /api/orders/12345
Resource MIME Types
Resource representation is how a resource that’s identified by URI is encoded and transported over the HTTP protocol in a specific format, such as XML or JSON. Clients that want to retrieve a specific resource must use the URI in the request to the API. The API responds by returning a resource representation of the data indicated by the URI.
POST https://api.contoso.com/orders
Content-Type: application/json; charset=utf-8
Content-Length: 57
{“Id”:1,”Name”:”Gizmo”,”Category”:”Widgets”,”Price”:1.99}
If the server doesn’t support the media type, it should return HTTP status code 415 (Unsupported Media Type).
A client request can include an Accept header that contains a list of media types that the client accepts from the server in the response message. For example:
GET https://api.contoso.com/orders/2
Accept: application/json, application/xml
