Back
Nov 6, 2021

Top 5 Restful API Design Best Practices

Vladimir Sidorenko
Vladimir Sidorenko

5 Best Practices of RESTful API Design to Keep Your Users Happy


What is REST? Representational State Transfer (REST) was created as an idea to use simple HTTP in order to make calls between virtual machines, instead of such complex techniques as the Remote Procedure Call (RPC), Common Object Request Broker Architecture (CORBA), or Simple Object Access Protocol (SOAP). REST is not standard but, rather, it is an architectural style or set of principles geared at creating APIs to ensure interoperability between Internet-based computer systems.

The main advantages of REST are:

  • Simplicity;
  • Fast performance;
  • Fully-featuring;
  • Reliability; and,
  • Scaleability.

Besides being simple, fast, and reliable, REST API design patterns allow developers to implement any features in their web services. There are no features that cannot be recognized in web applications through REST. In this blog post, you will learn about REST API design best practices, how a typical RESTful API should be built and how to optimize it even further. These tips will be useful for startup owners, large IT business proprietors, or enthusiasts who have the need to create a web service. And as additional information to this article, read about how to find a developer for your startup.

IMPORTANT PRINCIPLES OF A RESTFUL API DESIGN BEST PRACTICES

Building a great API is a serious issue that comes across the desk of many reputed development teams that build web services. A well-structured design is able to boost the implementation process and help avoid complex configurations that can decrease API performance. It facilitates resource management and helps prevent chaos and confusion during development. A design is as important for building an efficient API as its functions. A good API design ensures an improved developer experience and high adoption of your solution. 

SIMPLICITY

A good API has to be easy to read and use and, when working with it, it should be simple and comprehensive. Programmers who use your API should spend minimum time working with the solutions. For that reason, the API’s associated operations and resources have to be easily memorized and understood.

COMPLETENESS

A good REST API design example is when the solution requires no additional applications for solving related tasks. A complete solution is able to operate data in a fast and secure way. Furthermore, a reliable API should include comprehensive logic to allow for the creation of new APIs on top of the existing one, and upon future request.

CORRECTNESS

Implementing a custom well-designed API can bring various benefits to those who are going to use it. A well-tested and bugless solution will ensure high performance and efficient task management. A correctly functioning API requires no strict and highly detailed guidelines of how-to-use it.

HOW TO BUILD A RESTFUL API: BEST PRACTICES

The main omissions of many APIs are that they often have little in common with traditional REST semantics. Their working principles may be based on overly frequent changes being made, and they also often don’t have proper documentation or do not validate the data they use or expose. In API development, there is rarely a place for creativity. The solution should do what it is expected to do, and have an intuitive design to facilitate that. In the next paragraph, we will consider both technical and semantical aspects that should be implemented in terms of  RESTful API best practices to ensure high performance and stability.

REST API NAMING CONVENTIONS

It’s true that proper semantics may not make a customer’s life easier. Whatever naming conventions you use in your API, your solution will work the way it should if all other variables match. Adopting semantic conventions in your tool will help facilitate the work for those who use it. Below, we will list the basic naming principles you should follow to make your customers happy with your solution. Nouns Are Preferable, Over Verbs REST-styled code is based on nouns, with verbs being utilized mostly for commands. Use nouns to define the path for a particular command, as follows:

GET / users is better than GET / getUsers GET /users/987 is better than GET /getUserWithId/987 POST /users is better than GET /createNewUser

The first variants are preferable for RESTful APIs: they are simpler and more comprehensive from the REST perspective.

Plural Nouns Are Preferable, Rather Than Singular

Using plural or singular nouns for defining resources has no any impact on how your API will work; however, there are common conventions that are used in all good RESTful APIs. One of such conventions is the use of plural nouns for defining resources.

/users is better than /user and /users/16 is better than /user/16

Note: avoid mixing singular and plural nouns.

Represent Complex Parameters with a Query String

In RESTful APIs, a query string (“?”) is commonly used for setting complex parameters to define resources. It keeps the URL short, logical, and simple. Remember that all optional parameters have to be recognized through a query string.

GET /users?location=US&age=21 is better than

GET  /users
GET /US-basedUsers
GET  /US-basedUsersAnd21-agedUsers

Note: Choose one naming form and stick to it during the whole development process.

REST API Pagination

Pagination ensures the easy handling of numerous request results. For example, your web service contains hundreds or thousands of pages. When you request to display all its pages, you will get the same number of results, in return. It overloads the user interface and takes more time to display. Pagination divides the results by specific parts and displays them in the specific order. Also, you can find more about user interface design for web applications in our blog.

Use a Limit Parameter

When you request some data and you know the results will fill numerous pages, you should set the limit of results per one page:

GET "http://resource.../page?limit=10";

The limit, which is set after the query string, regulates the number of results that have to be displayed on one page. Use a Start Parameter If you need to display specific results on a page, you should use a “start” parameter. Set a limit parameter and the first result which should be displayed after the query string:

GET "http://resource.../page?limit=10&start=21";

This command will display the page with ten results starting from the 21st one.

REST API URL Format

Avoid Using a Forward Slash at the End of the URL

A trailing forward slash (“/”) has no semantic meaning and can lead to confusion. That is why a forward slash should be avoided when forming the URL, despite the fact that gearheart.io/portfolio/ and gearheart.io/portfolio will be treated equally by most web frameworks and components. Furthermore, a good RESTful API will use the 301st redirect to display the page without a forward slash in the URL.

Use a Forward Slash to Set a Relationship

Using a forward slash for indicating a hierarchy in the URL has become a commonly used principle:

/forbes.com/technology/#5b89537f4bad

This example shows a relationship between a home page “forbes.com” and the category “technology.”

Use a Hyphen to Increase URL Friendliness

To allow users easily read your URL, use hyphens (“-”) or even a camel case, instead of one long line of words. In all RESTful APIs, a hyphen equates to a space:

/techcrunch.com/2017/09/24/techcrunchs-startup-battlefield-australia-joined-by-leading-aussie-names/

Avoid Using Underscores in URLs

Taking into account that web browsers usually underline links to inform users that the URL is clickable, you should avoid using underscores ("_") to define resources. The browser’s underlining format will hide your underscore, which can confuse users.

Use Lowercase Letters for Resources

Using uppercase letters to define resources makes the URL key sensitive, which may lead to confusion in particular situations. Using lowercase letters will ensure the correctness of the command, even if the URL was input with uppercase letters, but not vice versa:

/gearheart.io/contacts/ and /gearheart.io/Contacts/

If you use the second form to define the resource, it will not work and display an error.

Avoid Using File Extensions

RESTful APIs should not include a period to indicate a file extension. Instead, they must use the media type to determine how content should be processed. To ensure easy debugging, your API should provide the selection of media types using query parameters.

FAQ

1. What are the RESTful API design best practices? 

  • Validation;
  • Session based authentication;
  • No sensitive data in URL;
  • Restriction on Method execution;
  • Validate Malformed XML/JSON;
  • Throw generic Error Messages.

2. What a well-designed web API should support?

Typically, web API design best practices meet the following points:

  • Platform independence. Any client should be able to call the API, no matter how the API is internally implemented.
  • Service evolution. The web API should be able to evolve and add functionality independently of the client applications, and existing client applications should continue to work unchanged.

3. What are the common HTTP methods used by RESTful API?

  • GET returns a representational view of a resource's contents and data.
  • POST creates a new resource at the specified URL and operates on resource collections.
  • PUT either creates or replaces the resource.
  • PATCH is used to update resources.
  • DELETE deletes the resource entirely.
     

More thoughts

May 9, 2018Technology
How to Generate PDF Files in Python with Xhtml2pdf, WeasyPrint or Unoconv

Programmatic generation of PDF files is a frequent task when developing applications that can export reports, bills, or questionnaires. In this article, we will consider three common tools for creating PDFs, including their installation and converting principles.

Vladimir Sidorenko
Vladimir Sidorenko
Jan 12, 2017Technology
Making Custom Report Tables Using AngularJS and Django

In this article I will tell you how to create an interactive interface with a widely customized visual look and different filtering to view reports.

Pasha Volkov
Pasha Volkov
Feb 12, 2020Technology
5 Best Payment Gateways For 2020

We reviewed the best payment gateways in 2020. Here’s our comparison of their features, advantages, and disadvantages.

Vladimir Sidorenko
Vladimir Sidorenko
Apr 3, 2011Technology
Sprite cache invalidation

When we use css-sprites it's important to make browser cache them for longest period possible. On other hand, we need to refresh them when they are updated. This is especially visible when all icons are stored in single sprite. When it's outdated - entire site becomes ugly. To solve this task I've implemented this small script that adds file's hash to url:background-image: url(images/icons.png?a3844c660);

Vladimir Sidorenko
Vladimir Sidorenko
Mar 7, 2017Technology
How Do You Use MongoDB With Python?

There are many ways to interact with MongoDB using Python. In this article we'll compare them and will help you make a decision.

Vlada Oliinyk
Vlada Oliinyk
Feb 28, 2010Technology
Composing multiple views in Django

In UNIX way, each view should solve single task. This is good idea, but sometimes we need to mix logic of different views on same page. Filter, sort, paginate, or, for example, add comment on product page. In this article I'll show how we can mix such multiple views.

Vladimir Sidorenko
Vladimir Sidorenko