What Is a RESTful API? [Part 2]

This is the second part of my API design basics series. Please read the first part before continuing. In this post I will cover HTTP Status Codes, Pagination, Filtering, Sorting and Searching.

Status Codes

After making a request, the server usually responds with a status code. This code indicates whether the request succeeded. If it failed, it includes the reason why the failure occurred. Let’s consider the famous 404 – Not Found Status Code. Open your browser and go to https://www.stcloudstate.edu/ThisUrlDoesNotExist . Now use either your browser’s developer tool or Fiddler to see the request and response. I am using Fiddler and this is what I see:

404

As seen on this picture, the server responded with a 404 to my intentionally erroneous request.

The 404 is not the only status code out there, in fact there are 5 categories of HTTP status codes. They consist of three digits and their category is defined by the first digit, 4 in the example of 404. The next two digits identify the code among the codes of its category. These are the categories of the status codes:

  • 1xx (Informational): The request was received, continuing process
  • 2xx (Successful): The request was successfully received, understood, and accepted
  • 3xx (Redirection): Further action needs to be taken in order to complete the request
  • 4xx (Client Error): The request contains bad syntax or cannot be fulfilled
  • 5xx (Server Error): The server failed to fulfill an apparently valid request

Let’s look at what each status code class is used for. An informational response indicates that the request was received and understood. It is issued on a provisional basis while request processing continues. It alerts the client to wait for a final response

1xx Informational response from a server means that the server received and understood the request and is working on it. It asks the client to wait for the final response. These codes are not used too often and if you open Fiddler, browse some websites and look at what requests and responses you have, you will likely not see any 1xx responses.

2xx Successful responses indicate that the user’s request was received, understood and accepted.

3xx Redirection responses usually mean that the resource requested by the user was moved to a different URL either temporarily or permanently. If it was moved temporarily, then the browser will continue to make requests to the very same URL and will be redirected to the new one every time a request is made. However if the resource was moved permanently then the browser is asked to make the requests only to the new URL. The 301 Moved Permanently response code is widely used to upgrade the HTTP requests to HTTPS. The Location field of the response will contain the new URL to be used. Let’s try this out. Open Fiddler once more, Go to the Filters tab and in the second dropdown called Hosts, type in youtube.com. Then click on Actions… and select “Run Filterset now”. Now only requests and responses from youtube.com will appear. Then open the browser and go to http://youtube.com . This is what you should see:

301

Notice that we made a GET request using HTTP protocol version 1.1 to host youtube.com and received a response with a code of 301 Moved Permanently to the location of https://www.youtube.com

The 4xx class of status codes is reserved for situations when the client’s request seems to be erroneous. The codes contain information why the error is occurring and the most used ones are:

  • 400 Bad Request – apparent client error such as malformed request syntax
  • 401 Unauthorized – the user is not authorized and is not allowed to perform the requested operation/access a resource
  • 404 Not Found – the requested resource was not found (check out the demo in the beginning of the article)

Finally, the 5xx codes indicate that the server was unable to process the request. Most likely, the request was valid but there was an error on the backend of the application and therefore the request could not be fulfilled.

You can read more about status codes here (https://en.wikipedia.org/wiki/List_of_HTTP_status_codes )

Pagination

Say you make a GET request to http://moviestore123.com/movies . How many individual movies will you get back? Is it 10? 100? 1000? The answer is – it depends. Usually you want to limit the number of results returned per request. So when the user requests a resource, they would send a request like this:

GET /movies/?page=1

Notice the ?page=1 part of the request. This says that the user wants the first page of the results only. The response to this request would then contain a field like:

“total_pages”: 102

So the user would know how many more pages they can request.

GIST of response

For example, if you are using Spring Boot, a Controller like this would do the job

http://localhost:8080/listPageable?page=0&size=3&sort=name

Filtering

In order to make our request to the API more specific, we can specify different parameters like this:

GET /movies?category=adventure&country=usa

After this request is executed and the category name as well as the country where the film was shot will be included.

Sorting

If the amount of data returned is big and the client needs a list of sorted items, then sorting the objects on the server side makes sense. One can sort the data by values of different fields stored in the database. For example, in the request below the movies are sorted in the descending order, based on their budget.

GET /movies?sort=budget_desc

Searching

We can also search for a particular company using an endpoint like this:

GET /movies?search=Fury

Thank you for reading this article and if you have any questions, please let me know in the comments! I plan to write another post that will go into HATEOAS, authentication, returning data in JSON vs XML!

Leave a Reply

Your email address will not be published. Required fields are marked *