HTTP Methods for RESTful Services
The common HTTP methods! GET, POST, PUT, PATCH and DELETE
Prerequisites:
- None
Terminology
The methods:
DELETE: delete a resource identified by a URI
GET: requests data from a specified endpoint
PATCH: used to modify resources
POST: sends data to a specified endpoint to create or update a resource
PUT: used to update resources
Others:
Idempotent: An operation that produces the same results if executed multiple times
JSON: JavaScript Object Notation, a lightweight format for storing and transporting data
URI: Uniform Resource Identifier
The HTTP Verbs
POST
We can think of POST as a way to create new resources.
Creating
Typically the resources that are created are subordinate resources; that we POST to the parent and the service associates the new resource to the parent.
On Success
We should expect a HTTP status of 201 to be returned, including a link to the newly created resource.
Idempotent?POST is not idempotent, although making two identical POST request is expected to result in two identical resources
Example
http://www.example.com/customers
GET
We think of GET requests as a way to retrieve resource(s)
Read
We can read existing resources which are usually returned in JSON format to the client
On Success
We should expect a HTTP status of 200 (OK) to be returned, with a representation of the request usually in JSON format.
Idempotent?
Because we are reading resources, they should be the same every time. There should also be no risk of corruption since we are reading resources rather than creating or changing any.
Example
http://www.example.com/customers/12345
PUT
We think of PUT requests as a way to update resource(s)
Update
When updating resources we can expect an existing resource to be replaced with an updated resource. If an update is run on a resource that does not currently exist PUT creates the resource and returns 201 to represent a successful creation of the resource.
On Success
A successful update returns 200, but if the resource is created a 201 is returned. A body can be returned but is optional.
Idempotent?
A PUT can be a counter, which clearly identifies that a PUT request may not be idempotent, and it is advised that the documentation records if the request is idempotent
Example
http://www.example.com/customers/12345
PATCH
A PATCH request modifies resources, and to do so only contains the changes to the resource (that is, the patch rather than a complete resource)
patchPATCH is superficially similar to PUT, but does not consume as much bandwidth by sending a complete resource. The patch itself can be thought of as a set of instructions that update the existing resource using a patch language (JSON Patch is one such language)
On Success
A successful patch returns 200.
Idempotent?
Patches update the resource, so we would not expect the request to be idempotent unless care is taken to make it so (and equally prevent collisions between multiple patch requests).
Example
http://www.example.com/customers/12345
DELETE
A DELETE removes a resource
deleteDELETE removes a resource specified by a URI.
On Success
A successful deletion returns 200.
Idempotent?
By definition this is notidempotent as calling a DELETE multiple times can be expected to return a 404 NOT FOUND as DELETE has already been called on the resource.
Match the HTTP Verbs to CRUD Operations
Conclusion
You’d be well advised to know something about HTTP methods during your software development career. You’d be surprised how many developers are confused between PUT and PATCH (for example). This guide should give you some indication of the differences, and the responses you can expect from your client.
Hey! If you like it, why not hit me up on Twitter?
Extend your knowledge
You can read more about REST and CRUD through this link
The Twitter contact:
Any questions? You can get in touch with me HERE
