The most common HTTP verbs (or HTTP methods) used with RESTful services are GET, POST, PUT, PATCH and DELETE. The below table summarizes their usage with RESTful services:
| Method | Usage | Success Response | Failed Response |
|---|---|---|---|
GET | Read | 200 (OK) | 400 (Bad Request) 404 (Not Found) |
POST | Create | 201 (Created) | 400 (Bad Request) 409 (Conflict) |
PUT | Update (Replace) | 200 (OK) 204 (No Content) | 400 (Bad Request) 404 (Not Found) 406 (Method not Allowed) 409 (Conflict) |
PATCH | Update (Modify) | 200 (OK) 204 (No Content) | 400 (Bad Request) 404 (Not Found) 406 (Method not Allowed) 409 (Conflict) |
DELETE | Delete | 200 (OK) | 404 (Not Found) |
Example
The below examples use a dummy endpoint containing resources for heroes:
https://www.domain.com/api/heroesA hero resource has the following structure:
GET
The HTTP GET method is used to only read a representation of a resource and not change it. The below request will retrieve all hero resources:
GET https://www.domain.com/api/heroesPagination, sorting and filtering should be used to navigate big lists. The below request is an example used to return a specific list of heroes:
GET https://www.domain.com/api/heroes?offset=&limit=&sortby=&sortorder=&filter=The below request is used to get a single resource by a unique identifier:
GET https://www.domain.com/api/heroes/:idThe GET method can also be applied to retrieve subordinate resources. For example, achievement resources for a hero can be retrieved as follows:
GET https://www.domain.com/api/heroes/:id/achievements
GET https://www.domain.com/api/heroes/:id/achievements?offset=&limit=&sortby=&sortorder=&filter=
GET https://www.domain.com/api/heroes/:id/achievements/:achievementIdPOST
The HTTP POST method is used to create a new resource. The below request is used to create a resource:
POST https://www.domain.com/api/heroesThe details of the hero are placed in the body of the request. On successful creation of a resource, a response with a 201 HTTP status code and a Location header containing a link to the newly-created resource will be returned.
A POST request can also create subordinate resources. When creating a new subordinate resource, POST to the parent resource takes care of associating the new resource with the parent. For example, assume that a hero resource contains a list of achievements, an achievement can be created as follows:
POST https://www.domain.com/api/heroes/:id/achievementsPUT
The PUT method is usually used to update or replace a resource. The below request is used to replace a resource:
PUT https://www.domain.com/api/heroes/:idThe below request is used to replace a subordinate resource:
PUT https://www.domain.com/api/heroes/:id/achievements/:achievementIdA PUT method will return a 200 status code in a success response. HTTP status code 204 is returned if no content is contained in the response body.
PATCH
The PATCH method is usually used to modify an existing resource. The PATCH request only needs to contain the changes to the resource, not the complete resource. The below request is used to modify an existing resource:
PATCH https://www.domain.com/api/heroes/:idThe below request is used to modify a subordinate resource:
PATCH https://www.domain.com/api/heroes/:id/achievements/:achievementIdA PATCH method will return a 200 status code in a success response. HTTP status code 204 is returned if no content is contained in the response body.
DELETE
The DELETE method is used to delete a resource. The below request is used to delete a resource:
DELETE https://www.domain.com/api/heroes/:idThe below request is used to delete a subordinate resource:
DELETE https://www.domain.com/api/heroes/:id/achievements/:achievementIdSummary
Using HTTP methods correctly in a RESTful service is useful and provides consistency across all API implementations.
Further information on HTTP methods can be found at the following link: