DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Please enter at least three characters to search
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

Last call! Secure your stack and shape the future! Help dev teams across the globe navigate their software supply chain security challenges.

Modernize your data layer. Learn how to design cloud-native database architectures to meet the evolving demands of AI and GenAI workloads.

Releasing software shouldn't be stressful or risky. Learn how to leverage progressive delivery techniques to ensure safer deployments.

Avoid machine learning mistakes and boost model performance! Discover key ML patterns, anti-patterns, data strategies, and more.

Related

  • Node.js REST API Frameworks
  • Update User Details in API Test Client Using REST Assured [Video]
  • Create User API Test Client With REST Assured [Video]
  • How to Make a REST API Call in Angular

Trending

  • Performing and Managing Incremental Backups Using pg_basebackup in PostgreSQL 17
  • Intro to RAG: Foundations of Retrieval Augmented Generation, Part 1
  • Building Enterprise-Ready Landing Zones: Beyond the Initial Setup
  • Revolutionizing Financial Monitoring: Building a Team Dashboard With OpenObserve
  1. DZone
  2. Software Design and Architecture
  3. Integration
  4. Top REST API Best Practices

Top REST API Best Practices

In this blog post, my goal will be to explain REST as clearly as possible so you can clearly understand when and how to use it, as well as what it is in essence.

By 
Vladimir Pecanac user avatar
Vladimir Pecanac
·
Updated Sep. 07, 20 · Analysis
Likes (59)
Comment
Save
Tweet
Share
110.4K Views

Join the DZone community and get the full member experience.

Join For Free

You can read the original/updated article on Code Maze blog.

Many giants like Facebook, Google, GitHub, Netflix, Amazon, and Twitter have their own REST(ful) APIs that you can access to get or even write data.

By why all the need for REST?

Is it that good and why is it so prevalent?

Surely it's not the only way to convey messages?

What is the difference between REST and HTTP?

Well, it turns out REST is pretty flexible and compatible with HTTP (which is the main protocol the internet is based upon). Since it is an architectural style and not the standard, it provides a lot of freedom to implement various design best practices. Did I mention it's language agnostic?

In this blog post, my goal will be to explain REST as clearly as possible so you can clearly understand when and how to use it, as well as what it is in essence.

We'll go through some basics and definitions as well as show off some REST API best practices. This should give you all the knowledge you need to implement REST APIs in any language in which you prefer to code.

If you are not that familiar with HTTP, I recommend reading our HTTP series, or at least part 1 of it, so you can digest this material more easily.

So What Is REST Essentially?

REST (Representational State Transfer) is an architectural style founded by Roy Fielding in his Ph.D. dissertation "Architectural Styles and the Design of Network-based Software Architectures" at UC Irvine. He developed it in parallel with HTTP 1.1 (no pressure).

We use REST primarily as a way to communicate between computer systems on the World Wide Web.

Is REST Bound to HTTP?

By definition, it's not. Although you can use some other application protocol with REST, HTTP has remained the undisputed champion among application protocols when it comes to the implementation of REST.

What Does RESTful API Mean?

"RESTful" implies a few features:

  • Client-server architecture: The complete service is comprised of the "Client" which is the front-end and the "Server" which is the backend part of the whole system.
  • Stateless: The server should not save any states between different requests. The state of the session is exclusively left to the responsibility of the client. As per the definition of REST: All REST interactions are stateless. That is, each request contains all of the information necessary for a connector to understand the request, independent of any requests that may have preceded it. (Roy's dissertation ch. 5.2.2)
  • Cacheable: The client should be able to store responses in a cache for greater performance.

So, the RESTful API is a service that follows these rules (hopefully) and uses HTTP methods to manipulate the set of resources.

But why do we need or use RESTful APIs?

Because they give us an easy, flexible, and scalable way to make distributed applications that communicate over the internet.

Can We Have Too Much REST?

Yes, you guessed it. Yes, we can. 

There is even a phrase for the people that follow REST fanatically, as defined by Mike Schinkel.

A RESTifarian is a zealous proponent of the REST software architectural style as defined by Roy T. Fielding in Chapter 5 of his Ph.D. dissertation at UCIrvine. You can find RESTifarians in the wild on the REST-discuss mailing list. But be careful, RESTifarians can be extremely meticulous when discussing the finer points of REST, as I learned recently while participating on the list. 

Too much of anything can be bad.

We need a bit pragmatism to make good applications and services. A theory is important to know and understand, but the implementation of that theory is what differentiates bad vs good vs excellent applications. So be smart, have the end user in mind.

So let's look at some important points that make APIs "shine" and the lives of the users a whole lot easier.

Abstract vs Concrete APIs

When developing software we often use abstraction and polymorphism to get most of our applications. We want to reuse as much of the code as possible.

So should we write our APIs that way too?

Well, that is not exactly the case with APIs. For REST APIs, concrete is better than abstract. Can you guess why?

Let me show you a few examples.

Let's look at two API versions. Is it better to have an API that has one /entities or an API that has /owners, /blogs and, /blogpostsseparately?

Which one seems more descriptive to you as a developer? Which API would you rather use?

I would always choose the second one.

URI Formatting (Nouns, not Verbs): Good URL vs Bad URL Examples

Here is another REST API best practice. How should you format your endpoints?

If you use the software development approach you will end up with something like this:

/getAllBlogPosts

/updateBlogPost/12

/deleteBlogPost/12

/getAuthorById/3

/deleteAuthor/3

/updateAuthor/3

You get the point... There will be a ton of endpoints, each one doing something else. There is a better system for sorting out this mess.

Treat the resource like a noun, and the HTTP method as a verb. If you do it like that, you'll end up with something like this:

GET /blogposts - gets all the blog posts.

GET /blogposts/12 - gets the blog post with the id 12.

POST /blogposts - adds a new blog post and returns the details.

DELETE /blogposts/12 - removes the blog post with the id 12.

GET /authors/3/blogposts - gets all the blog posts of the author with id 3.

This is a cleaner and more precise way to use the API. It is immediately clear to the end user, and there is a method to the madness.

You can make it even cleaner by using singulars instead of plurals for the resource names. That one is up to you.

Error Handling

This is another important aspect of  API building. There are a few good ways to handle errors.

Let's see how the top dogs do it.

Twitter:

  • Request: GET https://api.twitter.com/1.1/account/settings.json 
  • Response: Status Code 400
JSON
 




xxxxxxxxxx
1


 
1
{
2
  "errors": [
3
    {
4
      "code": 215,
5
      "message": "Bad Authentication data."
6
    }
7
  ]
8
}


Twitter gives you the Status Code and Error Code with the short description of the nature of the error that occurred. They leave it up to you to look the codes up on their Response Codes page.

Facebook:

  • Request: GET https://graph.facebook.com/me/photos 
  • Response: Status Code 400
Java
 




xxxxxxxxxx
1


 
1
{
2
  "error": {
3
    "message": "An active access token must be used to query information about the current user.",
4
    "type": "OAuthException",
5
    "code": 2500,
6
    "fbtrace_id": "DzkTMkgIA7V"
7
  }
8
}


Facebook gives you a more descriptive error message.

Twilio:

  • Request: 
  • GET https://api.twilio.com/2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234
  • Response: Status Code 404
XML
 




xxxxxxxxxx
1


 
1
<?xml version='1.0' encoding='UTF-8'?>
2
<TwilioResponse>
3
    <RestException>
4
        <Code>20404</Code>
5
        <Message>The requested resource /2010-04-01/Accounts/1234/IncomingPhoneNumbers/1234 was not found</Message>
6
        <MoreInfo>https://www.twilio.com/docs/errors/20404</MoreInfo>
7
        <Status>404</Status>
8
    </RestException>
9
</TwilioResponse>



Twilio gives you an XML response by default and the link to the documentation where you can find the error details.

As you can see, the approaches to error handling differ from implementation to implementation.

The important thing is not to leave the user of the REST API "hanging," i.e. not knowing what happened or aimlessly wandering through the wastes of StackOverflow searching for the explanation.

Status Codes

When designing a REST API, you communicate with the API user by utilizing HTTP Status Codes. There are a lot of status codes, describing multiple possible responses.

But just how many should you use? Should you have a strict status code for every situation?

As with many things in life, the KISS principle applies here too. There are over 70 status codes out there. Do you know them by heart? Will the potential API user know them all, or will it once again result in googling stuff?

Most developers are familiar with the most common status codes:

  • 200 OK 
  • 400 Bad Request 
  • 500 Internal Server Error 

By starting with these three, you can cover most of the functionalities of your REST API.

Other commonly seen codes include:

  • 201 Created 
  • 204 No Content 
  • 401 Unauthorized 
  • 403 Forbidden 
  • 404 Not Found 

You can use these to help the user quickly figure out what the result was. You should probably include some kind of message if you feel the status code is not descriptive enough like we discussed in the error handling section. Once again, be pragmatic, help the user by using a limited number of codes and descriptive messages.

You can find the complete HTTP Status codes list, as well as other helpful HTTP stuff here.

Security

There is not much to be said about REST API security because REST doesn't deal with security. It relies upon standard HTTP mechanisms like basic or digest authentication.

Every request should be made over HTTPS.

There are many tricks to improve the security of your REST API, but you must be cautious when implementing them, because of the stateless nature of REST. Remembering the state of the last request goes out of the window, and the client is where the state should be stored and verified.

Timestamping and logging requests can help a bit too.

There is much more to be said on this topic, but it is out of the scope of this post. We have a nice post on HTTP Security if you want to learn more about that.

REST API Versioning

You've already written your REST API and it has been very successful and many people have used it and are happy with it. But you have that juicy new functionality that breaks other parts of the system. The breaking change.

Never fear, there is a solution for that!

Before you start making your API, you can version your API by prefixing the endpoints by the API version: https://api.example.com/v1/authors/2/blogposts/13

This way you can always increment your API version number (eg. v2, v3...) whenever there are breaking changes in your API. This also signals to the users that something drastic has changed and they should be careful when using the new version.

Importance of Documentation

This one is a no-brainer. You could be the best API designer in the world, but without documentation, your API is as good as dead.

Proper documentation is essential for every software product and web service alike.

You can help the user by being consistent and using clear and descriptive syntax, sure. But there is no real replacement for good ol' documentation pages.

Here are some of the great examples:

  • https://www.twilio.com/docs/api/rest/

  • https://developers.facebook.com/docs/

  • https://developers.google.com/maps/documentation/

There are many tools that can help you document your API, but don't forget to add the human touch, only one human can properly understand another. For now at least (looking at you AI).

Conclusion

We went through many concepts of the REST API building and covered some of the top REST API best practices. These might seem a bit strange or overwhelming when served at once, but try making your own REST API. And try to implement some the REST API best practices you learned here.

Make the tiniest API possible and see how it looks. You'll be surprised how well it can turn out by just following these few practices.

We have an ongoing series in which we will demonstrate some of these practices. Also, if you are a C# developer, check out our article on how to consume RESTful APIs in a few different ways.

And with this said, I REST my case ... kmhmh... you know, like in court...

Is there anything important I've missed? If I did, let me know in the comments section!

You can read the original/updated article on Code Maze blog.

REST Web Protocols API code style

Published at DZone with permission of Vladimir Pecanac. See the original article here.

Opinions expressed by DZone contributors are their own.

Related

  • Node.js REST API Frameworks
  • Update User Details in API Test Client Using REST Assured [Video]
  • Create User API Test Client With REST Assured [Video]
  • How to Make a REST API Call in Angular

Partner Resources

×

Comments
Oops! Something Went Wrong

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • support@dzone.com

Let's be friends:

Likes
There are no likes...yet! 👀
Be the first to like this post!
It looks like you're not logged in.
Sign in to see who liked this post!