REST API: the basics
By: Girija Shankar Behera
Tags: PROGRAMMING REST APIS, Programming Rest Apis

Let’s explore it further.

Parts of a Request

Let’s take a request URL and analyze what it is made up of.

Request URL

URL stands for Uniform Resource Locator. From the name it seems like an address of a Resource. The client can use this URL to get access to a resource. For our case, I want to see all the posts available on the server. As we can see above, the URL consists of a root endpoint and a path to the specific resource.

Request Endpoints constitutes of a root endpoint and a path to a specific resource. Image by Girija Shankar Behera

It looks for the posts available currently on the server. (or for a specific post on the server with its unique id, or for a comment on a post etc. The id accessed here refers to a specific post, it’s called URI, we see it in the next item).

Request Method

Client needs to indicate the type or the method of the request with the request itself. This tells the server what client actually wants to do with the request. It might be to access and read the resources, or might be to update one of them, or create a new one, or delete one. The method on the request lets the Server take appropriate action on the resources. REST allows the usage of the HTTP methods GET, PUT, POST and DELETE to perform CRUD operations. Below, we explore each of them in detail.

GET: A client may ask for a single item as a resource, with it’s unique identifier. In this case, the request method would be GET. It would be a simple Read operation.

Get a single item as a Resource. Image by Girija Shankar Behera

Here client is accessing a post with its unique identifier - id. Actually, it can be anything which is unique for each one of them, for ex. a username, or may be a phone number. The identifier is otherwise known as Uniform Resource Identifier (URI).

If the post with the requested ID is found, then the server creates a response including the post, in a JSON representation as shown above. It also returns the status code 200 with the response, as the resource was found. If not found it returns 404, or if identifier is not valid, it returns 400.

Get a multiple items as a Resource. Image by Girija Shankar Behera

A client may also ask for a list of items as a resource, without any identifier for a resource. In this case, the server creates a response including all the posts, in a JSON representation.

PUT: A client, if it has permissions, may ask to update the current state of the resource by sending an updated representation of it, in which case the server will update it to a new state.

Update a Resource. Image by Girija Shankar Behera

Here to update the resource, the client needs to send the new state (updated content) as well. The state can be sent in the body of the request, as it would be too large to fit on the url parameters. Also, we don’t want to send any sensitive information over a PUT request. After updating the resource state, it returns with a response of 200, or 204 if response has no content, or 404 if resource is not found.

POST: A client, if it has permissions, may ask to create a new resource itself by sending a representation of its desired state, in which case the server would create the resource.

Create a new Resource. Image by Girija Shankar Behera

Again as in the previous case, POST comes with a content in the body of the request, except that it is a new resource that client wants to create. Upon creation server responds with 201, or 204 with no content.

DELETE: A client, if it has permissions, may ask to delete a resource itself.

Delete a Resource. Image by Girija Shankar Behera

A delete operation comes again with the Unique Identifier for the resource which Client wants to delete from the server. Server returns 200 upon successful deletion, otherwise 404 if resource with identifier is not found.

Request Headers

Headers in the request contain meta information about the request. It allows the client to inform the server what format of the resource it is accepting, what encoding technique for the resource it is accepting, what language it is accepting, and many more tiny details that server might need while creating and sending the response.

Accept: This header is used to propose what content types the client would understand. Server negotiates with the client with one of these content types by sending the Content-type option in the response headers. Default one used is */* for accepting any type. Other values used are application/xml or application/json.

This header is used to propose what content types the client would understand. Server negotiates with the client with one of these content types by sending the Content-type option in the response headers. Default one used is */* for accepting any type. Other values used are application/xml or application/json. Accept-Encoding: This header is used to propose what encoding technique for the content client understands. Server negotiates with Content-Encoding option in one of the response headers. Values can be used are gzip, compress, br etc.

This header is used to propose what encoding technique for the content client understands. Server negotiates with Content-Encoding option in one of the response headers. Values can be used are gzip, compress, br etc. Authorization: This contains the credentials used to authenticate the client with the server. A common authorization technique used is “Basic” authentication scheme which encodes username and password with base64.

There are many more header fields available. Please have a look here to get a list of all of them and their by default values.

Request Body

Body of the request is an optional field. It contains the content of the resource which client wants to update or create. This field is populated when the request type is PUT or POST.

Parts of a Response

Let’s see what a Response is made up of:

Response Header

As we already saw in Request Headers, there are some Response headers as well. They are sent along with the response to the client. Two of them we saw above, Content-Type and Content-Encoding. Let’s see some more.

Allow: This header shows what methods are defined for a resource in the API definition. The values can be GET, POST, and PUT and DELETE.

This header shows what methods are defined for a resource in the API definition. The values can be GET, POST, and PUT and DELETE. Content Length: This indicates the size of the content sent to the client from the server. The size is in Bytes.

This indicates the size of the content sent to the client from the server. The size is in Bytes. Server: This header gives details of the server, i.e. the software used in the server side to generate the response.

Again there’s a bunch of them. Please have a look here to get a list of all of them and their by default values.

Status Codes

Status code in the REST API response is mainly used to indicate the result of the request to the client. The status codes are actually part of HTTP Response messages. In this post, we saw several status codes. To get the whole list of Status Codes please visit Status Codes.