What Are The Http Methods (Verbs) For Restful Services?

The name Representational state transfer (REST) was coined by Roy Fielding from the University of California. It is a very simplified and lightweight spider web service compared to Lather. Operation, scalability, simplicity, portability, and modifiability are the chief principles behind the Remainder design.

REST is a stateless, cacheable, and unproblematic compages that is not a protocol but a pattern.

In this tutorial, we will talk about Residuum verbs and status codes. The article is taken from the book Edifice RESTful Web services with Get by Naren Yellavula. In this book, you volition explore, the necessary concepts of Balance API development by building a few real-earth services from scratch.

Residuum verbs

REST verbs specify an action to be performed on a specific resource or a collection of resources. When a request is made by the client, information technology should ship this information in the HTTP request:

Remainder verb
Header data
Torso (optional)

Every bit we mentioned previously, REST uses the URI to decode its resource to be handled. There are quite a few Residuum verbs available, but six of them are used frequently. They are as follows:

GET
Mail service
PUT
PATCH
DELETE
OPTIONS

If you are a software developer, you will exist dealing with these 6 almost of the time. The following table explains the functioning, target resources, and what happens if the asking succeeds or fails:

Balance Verb	Activity	Success	Failure
`GET`	Fetches a tape or set of resources from the server	200	404
`OPTIONS`	Fetches all available REST operations	200	–
`POST`	Creates a new fix of resources or a resource	201	404, 409
`PUT`	Updates or replaces the given record	200, 204	404
`PATCH`	Modifies the given tape	200, 204	404
`DELETE`	Deletes the given resource	200	404

The numbers in the Success and Failure columns of the preceding table are HTTP status codes. Whenever a client initiates a REST functioning, since Remainder is stateless, the client should know a way to observe out whether the performance was successful or non. For that reason, HTTP has status codes for the response. REST defines the preceding status code types for a given operation. This means a REST API should strictly follow the preceding rules to achieve client-server advice.

All divers Residual services have the following format. Information technology consists of the host and API endpoint. The API endpoint is the URL path which is predefined by the server. Every Rest request should striking that path.

A footling Residue API URI:http://HostName/API endpoint/Query(optional)

Allow us await at all the verbs in more detail. The REST API design starts with the definition of operations and API endpoints. Before implementing the API, the design document should list all the endpoints for the given resource. In the following section, nosotros carefully detect the REST API endpoints using PayPal's REST API as a use case.

GET

A GET method fetches the given resource from the server. To specify a resource, Get uses a few types of URI queries:

Query parameters
Path-based parameters

In case you didn't know, all of your browsing of the web is done by performing a GET request to the server. For example, if you lot type www.google.com, you are actually making a GET asking to fetch the search page. Here, your browser is the client and Google's web server is the backend implementer of web services. A successful Become performance returns a 200 status code.

Examples of path parameters:

Everyone knows PayPal. PayPal creates billing agreements with companies. If you register with PayPal for a payment organisation, they provide yous with a REST API for all your billing needs. The sample GET request for getting the data of a billing agreement looks like this:/v1/payments/billing-agreements/agreement_id.

Here, the resource query is with the path parameter. When the server sees this line, it interprets it as I got an HTTP request with a need for agreement_id from the billing agreements. And so it searches through the database, goes to the billing-agreements table, and finds an agreement with the given agreement_id. If that resource exists it sends the details to re-create back in response (200 OK). Or else information technology sends a response proverb resource not constitute (404).

Using GET, you can also query a listing of resources, instead of a single one like the preceding instance. PayPal's API for getting billing transactions related to an agreement tin can be fetched with/v1/payments/billing-agreements/transactions. This line fetches all transactions that occurred on that billing agreement. In both, the case'southward data is retrieved in the grade of a JSON response. The response format should be designed beforehand so that the customer can consume information technology in the understanding.

Examples of query parameters are every bit follows:

Query parameters are intended to add detailed information to identify a resources from the server. For instance, take this sample fictitious API. Permit us assume this API is created for fetching, creating, and updating the details of the book. A query parameter based Go request will exist in this format:

                      /v1/books/?category=fiction&publish_date=2017

The preceding URI has few query parameters. The URI is requesting a book from the book'due south resource that satisfies the following weather condition:
- It should be a fiction volume
- The book should accept been published in the year 2017

Get all the fiction books that are released in the year 2017 is the question the client is posing to the server.

Path vs Query parameters—When to use them? It is a common rule of thumb that Query parameters are used to fetch multiple resources based on the query parameters. If a client needs a single resource with verbal URI information, it tin can employ Path parameters to specify the resources. For case, a user dashboard can be requested with Path parameters and fetch information on filtering can be modeled with Query parameters.

Employ Path parameters for a single resource and Query parameters for multiple resources in a GET request.

Post, PUT, and PATCH

ThePostal service method is used to create a resource on the server. In the previous book's API, this performance creates a new volume with the given details. A successful POST operation returns a 201 status code. ThePost request can update multiple resources:/v1/books.

TheMail asking has a body similar this:

{"proper noun" : "Lord of the rings", "year": 1954, "author" : "J. R. R. Tolkien"}

This actually creates a new book in the database. An ID is assigned to this record and so that when nosotros GET the resource, the URL is created. So Mail service should exist washed but one time, in the beginning. In fact, Lord of the Rings was published in 1955. So nosotros entered the published appointment incorrectly. In order to update the resource, let us use the PUT request.

ThePUT method is similar to POST. Information technology is used to replace the resource that already exists. The main difference is that PUT is idempotent. A Mail service telephone call creates 2 instances with the same data. But PUT updates a single resource that already exists:

          /v1/books/1256

with body that is JSON similar this:

          {"name" : "Lord of the rings", "yr": 1955, "author" : "J. R. R. Tolkien"}

1256 is the ID of the book. It updates the preceding book by twelvemonth:1955. Did you discover the drawback of PUT? It actually replaced the unabridged one-time record with the new one. We needed to modify a single cavalcade. But PUT replaced the whole record. That is bad. For this reason, thePATCH asking was introduced.

ThePATCH method is similar to PUT, except it won't replace the whole record. PATCH, as the name suggests, patches the column that is being modified. Allow us update the book 1256 with a new cavalcade called ISBN:

          /v1/books/1256

with the JSON body like this:

          {"isbn" : "0618640150"}

It tells the server,Search for the book with id 1256. Then add/alter this cavalcade with the given value.

PUT and PATCH both return the 200 status for success and 404 for not found.

DELETE and OPTIONS

TheDELETE API method is used to delete a resource from the database. It is like to PUT but without any torso. Information technology but needs an ID of the resource to exist deleted. In one case a resource gets deleted, subsequent Become requests return a 404 non found condition.

Responses to this method are not cacheable (in case caching is implemented) because theDELETE method is idempotent.

TheOPTIONS API method is the virtually underrated in the API development. Given the resource, this method tries to know all possible methods (GET, Postal service, and then on) defined on the server. It is like looking at the carte card at a restaurant and and then ordering an particular which is available (whereas if y'all randomly order a dish, the waiter will tell you information technology is not bachelor). It is best exercise to implement theOPTIONS method on the server. From the client, brand sure OPTIONS is called first, and if the method is available, then proceed with it.

Cantankerous-Origin Resource Sharing (CORS)

The most important application of this OPTIONS method isCross-Origin Resource Sharing (CORS). Initially, browser security prevented the client from making cross-origin requests. It ways a site loaded with the URL www.foo.com tin can only brand API calls to that host. If the customer code needs to asking files or data from www.bar.com, and so the second server, bar.com, should have a mechanism to recognize foo.com to get its resources.

This process explains the CORS:

foo.com requests the OPTIONS method on bar.com.
bar.com sends a header likeAccess-Control-Allow-Origin: http://foo.com in response to the client.
Next, foo.com tin can access the resources on bar.com without any restrictions that call any Balance method.

If bar.com feels like supplying resources to any host after one initial request, it can set Access control to * (that is, any).

The following is the diagram depicting the process happening ane after the other:

Types of status codes

There are a few families of status codes. Each family unit globally explains an operation status. Each member of that family may accept a deeper meeting. And then a REST API should strictly tell the client what exactly happened after the operation. There are threescore+ condition codes bachelor. Merely for Residual, we concentrate on a few families of codes.

2xx family (successful)

200 and 201 autumn under the success family unit. They indicate that an operation was successful. Obviously 200 (Operation Successful) is a successful CRUD Operation:

200 (Successful Functioning) is the most common blazon of response status code in Residual
201 (Successfully Created)is returned when a POST operation successfully creates a resources on the server
204 (No content) is issued when a client needs a status only not whatever data back

3xx family (redirection)

These condition codes are used to convey redirection messages. The well-nigh important ones are 301 and 304:

301 is issued when a resources is moved permanently to a new URL endpoint. It is essential when an one-time API is deprecated. Information technology returns the new endpoint in the response with the 301 status. By seeing that, the customer should use the new URL in response to achieving its target.
The 304 status code indicates that content is buried and no modification happened for the resources on the server. This helps in caching content at the client and only requests data when the cache is modified.

4xx family unit (customer mistake)

These are the standard error status codes which the customer needs to interpret and handle farther actions. These have nothing to do with the server. A wrong request format or ill-formed Balance method can cause these errors. Of these, the most frequent status codes API developers use are 400, 401, 403, 404, and405:

400 (Bad Request) is returned when the server cannot understand the customer request.
401 (Unauthorized) is returned when the client is not sending the authorization information in the header.
403 (Forbidden) is returned when the customer has no access to a certain blazon of resource.
404 (Not Found) is returned when the client asking is on a resource that is nonexisting.
405 (Method Not Immune) is returned if the server bans a few methods on resources. GET and HEAD are exceptions.

5xx family (server mistake)

These are the errors from the server. The client request may exist perfect, but due to a bug in the server lawmaking, these errors tin arise. The commonly used status codes are 500, 501, 502, 503, and504:

500 (Internal Server Error) condition code gives the development error which is acquired by some buggy code or some unexpected condition
501 (Non Implemented) is returned when the server is no longer supporting the method on a resource
502 (Bad Gateway) is returned when the server itself got an mistake response from some other service vendor
503 (Service Unavailable) is returned when the server is down due to multiple reasons, similar a heavy load or for maintenance
504 (Gateway Timeout) is returned when the server is waiting a long fourth dimension for a response from another vendor and is taking likewise much time to serve the client

For more than details on condition codes, visit this link: https://developer.mozilla.org/en-United states of america/docs/Web/HTTP/Condition

In this article, nosotros gave an introduction to the REST API and then talked about Residuum has verbs and status codes. We saw what a given status code refers to. Next, to dig deeper into URL routing with Balance APIs, read our book Building RESTful Spider web services with Become.

Read Side by side

Blueprint a RESTful web API with Java [Tutorial]

What RESTful APIs can do for Cloud, IoT, social media and other emerging technologies

Building RESTful spider web services with Kotlin