Restful API Design Guideline

Data sharing between two or more systems has always been a fundamental requirement of software development. Systems have the opportunity to use or process more than one data soruce in distributed architectures or 3rd party applications by exchanging information.

The most popular way of exchanging data between systems today is the Restful APIs. In this article, we will talk about what to pay attention to while developing Restful API and best practices accepted by many developers.

What is an API?

API (Application Programming Interface) is a module created for any application to use certain functions in other applications. It allows applications to communicate with each other without a user interface.

What is REST?

REST is a data transfer method used in software applications based on service oriented architecture. It runs on HTTP and is simpler than other alternatives. It is also faster because it sends and receives data with minimal content. It provides communication between client and server by carrying data in many different return types such as XML, JSON, CVS. Web services written in accordance with REST standards are called RESTful services.

REST is stateless, meaning it does not store state information. In REST standards, extra header information is not stored in the data transferred between client and server. Client details are not transferred between client and server. Therefore, REST offers us a lightweight solution structure in service oriented applications.

Terminologies

The following are the most important terms related to REST APIs:

Resource

Resources can be anything, entity, item or anything you want to export. E.G User, Product

Collections

Collections are a set of resources. E.G Products is the collection of the Product Resource.

URL

URL (Uniform Resource Locator) is a path through which a resource can be located and actions can be performed on it.

Best practices for Restful API development

There is no pattern or rule for Restful API development. I will mention the best practices accepted and frequently used by software developers.

Use Nouns instead of Verbs

Assume to model an API around a simple object or resource (product) and create a RESTful API that interacts with the product.

Consider the method calls required to handle all operations in the product resources. Our URLs might look like this:

/addProduct
/deleteProduct
/getProduct
/getAllProduct
/updateProduct

The URL must contain only names. Verbs such as add, update, delete, show above should not be added to URL.

We have to design it as “/products”. Ok, we’ve got the URL and name taken care of. So how are we going to do the operations on this endpoint? At this point, HTTP methods (GET, POST, DELETE, PUT) help us.

GET /products
returns all products

GET /products/1
return product with id 1

DELETE / products/1
delete the product with id 1

PUT /products
updates the product (id and data should be sent from body)

POST /products
add product (id and data should be sent from body)

Name the collections using Plural Nouns

Plural names should be used for collections while developing REST API.

For example:

GET /cars /11
POST /cars
GET cars

As seen in the first example above, it brings the details of the product which id is 11 from the list of all available “products”. Using “products” in the plural tells us that this is actually a collection of different product objects.

Use resource nesting to show relations or hierarchy

Resources often relate to different sources or have some sort of hierarchy between them. Continuing with the product and category scenario, a category can only be associated with multiple products. Accordingly, we can build our url as follows:

/categories
category list

/categories/11
specific category

/categories/11/products
a list of products belonging to a specific category

/categories/11/products/12
specific product of a particular category

Error Handling and Giving feedback to help developers succeed(Status Codes)

When the user makes a request to an API to get data from the server or make changes to existing data, the user must take a response from the server. There are status codes that can be used on the server side provided by HTTP. As a result of the request, the appropriate HTTP status code should be returned to the user by the server.

Main categories of HTTP Status Codes:

2xx (Success)

These status codes indicate that the client’s request was received by the server and successfully accepted.

200 “OK”

indicates that the REST API successfully responded to the action the client requested. A 200 status code response should return a response body as opposed to a 204 status code.

201

When a resource is successfully created, “Created” should be returned. For example, using the POST method to create a new resource should always return a status code 201.

202 “Accepted”

indicates that the client’s request is valid but needs time to process and will be processed asynchronously.

204 “No Content”

indicates that the customer’s request was successfully processed, but the API did not send any response bodies. The DELETE action is a good use case of this, when we ask the API to delete a resource, we don’t expect to receive data in the response body. If there is no resource to delete, the returned response status code must be in the 4xx Client Error category.

3xx (Redirection)

304 “Unmodified”

is used to conserve bandwidth by showing that the user has already received the most recent response in their cache, so there is no need to resend the same response.

4xx (Client Error)

400 “Bad Request”

indicates that the server could not understand what the client was looking for and therefore the request was rejected by the server.

401 “Unauthorized”

indicates that there is a problem with the customer’s credentials and they are not allowed to access this resource until they provide the appropriate credentials.

403 “Forbidden”

indicates that the request is correct and the client has been authenticated, but the client is not allowed to modify such resources. For example, the administrator has a high level of permissions, unlike a normal user.

404 “Not Found”

indicates that the REST API could not find the requested resource at this time.

405 “Method Not Allowed”

indicates that the HTTP method used is not allowed by the resource.

410 “Gone”

indicates that the resource is no longer available and was deliberately moved.

415 “Unsupported Media Type”

indicates that the media type provided by the customer’s request cannot be processed by the API

5xx (Server Error)

500 “Internal Server Error”

is a generic REST API error response indicating that the request was correct, but the server encountered some unexpected problems such as triggering an exception while processing the request.

503 “Service Unavailable”

indicates that the server is in maintenance and cannot currently process future requests.

Filtering, sorting and paging

Some of the features commonly used in APIs are filtering, sorting, and pagination. Collections often have a lot of data, and the user often may not need all of this information at once, or may need specific data, or need to fetch these data in a specific order.

Filtering, sorting and paging is used by adding a query parameter to the requested endpoint.

For example:

Filtering:

GET /categories?name=phones

Sorting:

GET /categories?sort=created_at:asc
GET / categories?sort=created_at:asc

Paging:

GET /categories?limit=50
GET /categories?offset=3

All together:

GET /categories?name=phones&sort=create_at:asc&limit=50&offset=3

This query should return the 150-200th row data in the source, increasingly according to the registration date with the category name is phones.

Versioning

If there is a radical change in the APIs used by the clients or if a transaction is made in the field used by the clients, we need to have different API versions. Versioning your REST API is a good approach to implement from the very beginning. Versioning allows you to make changes to your API and improve services.
Versioning is usually /v1/, /v2/, etc., appended to the beginning of the API path.

For example:

/v1/categories
/v2/categories

Conclusion

With the best practices mentioned in our article, it is possible to develop more consistent, precise, sustainable and understandable APIs. “How do I make it better?” You should definitely ask yourself the problem, otherwise, your workload will increase with the increase of technical debt in the future and you may experience a decrease in the number of clients using your APIs.