REST API Best Practice: Understanding Verbs and status code

Software developers have been working with REST architecture through HTTP and APIs. API isn't just an ordinary interface that you use to interact with the third-party program, communication between programs is done wrongly all because developers use the wrong HTTP status code to express responses. It is more difficult when exposing APIs that clients use to interact with applications in most modern web applications.

In this article, we'll explore in detail the most used REST verbs, the concept of CROS(Cross-Origin Resources Sharing), HTTP status code, and single-page applications with the REST API.

Table of Contents

• The REST Web Verbs
  • REST API Verbs
  • Path parameters vs Query parameters
• Cross-Origin Resources Sharing(CROS)
• HTTP Status Code
• REST API With Single Page Application(SPA)
  • The Old way of data flow in SPA
  • The Modern Way of Data Flow in SPA Through REST
• Conclusion

The REST Web Verbs

The information that should be sent when a request is made by the client must include the following:

• REST verbs

• Header Information

• Body(optional)

As a software engineer, you will work with these six REST verbs most of the time. The table below explains the operation, target resources, and what happens if a request fail or succeeds.

Since REST is stateless, the client should find a way to know if the operation was successful or failed. In this case, HTTP has a status code for responses. REST API strictly follow its rule to achieve client-server communication return.

http://HostName/API/endpoint/Query(optonal)
A well-defined REST service has the format above, which consists of the host and API endpoint

REST API Verbs

The REST API design start with the operation definition and the API endpoints the design document should list all the available endpoints for the given resources before implementing the API. To understand the REST verbs we should carefully observe the REST endpoints with examples.

GET
All the browsing on the web is done by performing a GET request to the website server which means GET fetches given resources from the server. A successful GET operation returns an OK (200 status code). GET uses two types of URL queries

• Path-based parameter

• Query parameter

Path parameters are request parameters attached to a URL that is to a specific rest of API resources. For example, PayPal creates a billing agreement with companies around the world, when a client registers with PayPal for a payment system, they provide a REST API for all the client billing needs and nd, and its GET request for billing looks like this:
/v2/payments/billings-agreements/agreement_Id
when the server sees it, and interprets it as I got an HTTP request for an agreement_Id from the billing agreement. If the request is on the database, it responds to 200 else it sends not-found 400

Query added detailed information to its resources from the server. for example, a movie API fetch, create and update the details of the movie. Query Get request format look like:
/v2/movies/?category=action&released_date=2023
The URL above has a query parameter requesting details from movie resources that satisfied the following conditions:

• It should be an Action movie

• The movie should have been released in the year 2023

Path parameters vs Query parameters

Query parameters are used to fetch multiple resources based on query parameters but if a client needs a single resource with specific URL information, it is best advised to use path-based parameters to specify the resources.

POST
post method is used to create new resources on the server. A successful post-operation returns a 201 status code. we'll use examples of previous movie creation, post request update multiple resources: /v2/movies.
The POST request json body looks like this:

{"name": "The woman king", "year": 2023, "Director ": "atanda0x"}

This creates a new movie in the database, it has an "id" assigned to the record so when GET calls the resources, the URL is created, and the post is done only once. Note that we entered the incorrect release year, in other to update the resources we use the PUT request

PUT
The put method is similar to that of the post method. it is used to replace the resources that already exist in the database. The main difference between the is idempotent, POST call creates two instances with the same data but PUT update a single resource that already exists:
/v2/movie/4289
with a JSON body that looks like this:

{"name": "The woman king", "year": 2022, "Director ": "atanda0x"}

The movie id is 4289. it updates the movie by "year:2022". PUT has a drawback which it updates the entire movie resources with the new one, and this is bad for a reason, the PATCH fixes this.

PATCH
PATCH came into play with the little setback of the PUT. It's similar to PUT except it won't replace the whole record with a new one. Since we need to change a column as the name implies it patches the column that is being modified: /v2/movies/4289
it JSON body looks like this:

{"ISBN":  "13337646743"}

It tells the server, to search for the book with Id 4289, and modify this column with the given value. Both PUT and PATCH return a 200 status code for success and a 404 for not-found.

DELETE
The DELETE method is used to delete resources that are no longer needed from the database. It has some similarities to PUT but without a body. It only needs an Id of the resources to be deleted, since the resources are deleted any GET request call from a client returns a 404 not-found.

OPTION
The OPTIONS method is not mostly used in all other API development. Given that it tries to know all available methods define in the server. We can describe it as a menu card in a restaurant, and then ordering available items. It is best practice to implement the OPTIONS method on the server.

Cross-Origin Resources Sharing(CROS)

The OPTIONS method led to cross-origin resource sharing. CROS is a protocol that enables controlled access to resources from any origin (schema, domain, port) other than its own from which a browser need to permit the loading of resources. Initially, browser security prevents clients from making a cross-origin request that is when a site loaded with a URL xyz.com can only make an API call to its host, and if a client need to request data from another URL abc.com, the second server should have a mechanism to recognize xyz.com to get its resources.

This logic explains the image above.

1. xyz.com request OPTION method on the abc.com server
2. abc.com send a header: Access-control-Allow origin: http://xyz.com in response to the client
3. xyz.com can access the resources on abc.com without restriction that calls the REST method
4. In some cases abc.com may feel like giving all its resources to any host after one initial request which it set access to * which means to any.

HTTP Status Code

HTTP works with Request & Response Model whenever a request is sent a response with a status code is received through this model. There are a few families of HTTP status codes, each family has different status and meaning. We concentrate on the most common families, which range from 100 to 500

1xx family(Informational)
Communicates transfer, protocol-level information family. They indicate that the server has received the request and is continuing the process. This family code is purely temporary and is given while the request processing continues. 100, 101, 102, and 103 fall under this family. A client doesn't encounter these much, as it's not the final request response.

• 100(Continue Operation) is an initial part of the request that has been received by the server and the client can proceed or ignore the response if the request has already finished.

• 102(Processing Operation) is returned when the server has accepted the full request but has not yet completed it, and the response is not available yet.

• 103(Early Hints) was intended to be used to allow a client to preload resources, while the server prepares a response. Like a primary user with the link header.

2xx family (successful)
200 and 201 fall under the success family. They indicate that an operation was successful. Plain 200 (Operation Successful) is a successful CRUD Operation:

• 200 (Successful Operation) is the most common type of response status code in REST.

• 201 (Successfully Created)is returned when a POST operation successfully creates a resource on the server

• 204 (No content) is issued when a client needs a status but does not have any data back.

• 205(Reset Content) is issued that the client should reset the document that this request.

• 206(Partial Content) is a response to a Range header sent from the client when requesting only a part of the resource.

• 226(IM response) is issued when the server has successfully fulfilled a GET request for a resource, and the response is a representation of the result of one or multiple instances applied to the current instance.

3xx family (redirection)
These status codes are used to convey redirection messages. The most important ones are 301 and 304:

• 301(Moved Permanently) is issued when a resource is moved permanently to a new URL endpoint. It is essential when an old API is deprecated. It returns the new endpoint in the response with the 301 status. By seeing that, the client should use the new URL in response to achieving its target.

• 304(Not Modified) status code indicates that content is cached and no modification happened for the resource on the server. This helps in caching content at the client and only requests data when the cache is modified.

4xx family (client error)
These are the standard error status codes that the client needs to interpret and handle further actions. These have nothing to do with the server. A wrong request format or ill-formed REST method can cause these errors. Of these, the most frequent status code API developers use are 400, 401, 403, 404, and 405:

• 400 (Bad Request) is returned when the server cannot understand the client's request.

• 401 (Unauthorized) is returned when the client is not sending the authorization information in the header.

• 403 (Forbidden) is returned when the client has no access to a certain type of resource.

• 404 (Not Found) is returned when the client request is on a resource that is nonexisting.

• 405 (Method Not Allowed) is returned if the server bans a few methods on resources. GET and HEAD are exceptions.

5xx family (server error)
These are the errors from the server. The client request may be perfect, but due to a bug in the server code, these errors can arise. The commonly used status codes are 500, 501, 502, 503, and 504:

• 500 (Internal Server Error) status code gives the development error which is caused by some buggy code or some unexpected condition.

• 501 (Not 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 error response from another service vendor.

• 503 (Service Unavailable) is returned when the server is down due to multiple reasons, like a heavy load or maintenance.

• 504 (Gateway Timeout) is returned when the server is waiting a long time for a response from another vendor and is taking too much time to serve the client.

REST API With Single Page Application(SPA)

Instead of building with the traditional UI way(request web page), SPA makes the building of UI a different way. There are many frameworks with the likes of Reactjs, Vuejs, Angulajs, and so on used to develop web page UIs rapidly and pretty simple. All frameworks help to implement one design pattern that is not requesting the web page but only REST API. Frontend is considered a separate entity that needs to talk to the backend only using REST API can achieve this. There are two ways data flow in SPA

The Old way of data flow in SPA

1. Request a web page from the server

2. Authenticate and show the dashboard UI

3. Allow the user to modify and save

4. Request as many web pages from the server as needed to show individual pages.

The Modern Way of Data Flow in SPA Through REST

1. Request the HTML template to the browser in one single go.

2. Query the JSON REST API to fill a model(data object)

3. It adjusts the UI according to the data in the model(JSON)

4. When a user modifies the UI, the model(data object) should change automatically.

Communication happens only in the form of the RET API, the client takes care of the logical representation of data. It causes The system to move from Response Oriented Architecture(ROA) to Service Oriented Architecture (SOA)

Conclusion

I hope you get to learn from this article teaches you about REST API, HTTP status code, REST verbs, and building with SPA. It's a long read, and I hope you find it worth it.

Kindly share your suggestion and comments, feedback in the comment section below.

You can also learn more about REST API on different platforms on the web browser.