Best Practices for Designing Developer-Friendly REST APIs

Best Practices for Designing Developer-Friendly REST APIs

REST APIs are probably the simplest way to integrate two applications over the Internet. Most web developers have integrated with or built them. I’ve written this guide to help developers design and build REST APIs that are easier to integrate with and easier to maintain. It includes tricks that I’ve borrowed from my colleagues, ideas that I learnt from books and articles, and some things from my own experience with REST APIs. So, you may find these best practices a bit opinionated. This guide starts with REST resources, then looks into requests and responses, then versioning, security, and, finally, developer experience. All practices here are platform- and language-agnostic. In this tutorial, you'll see Best Practices for Designing Developer-Friendly REST APIs

REST APIs are probably the simplest way to integrate two applications over the Internet. Most web developers have integrated with or built them.

I’ve written this guide to help developers design and build REST APIs that are easier to integrate with and easier to maintain. It includes tricks that I’ve borrowed from my colleagues, ideas that I learnt from books and articles, and some things from my own experience with REST APIs. So, you may find these best practices a bit opinionated.

This guide starts with REST resources, then looks into requests and responses, then versioning, security, and, finally, developer experience. All practices here are platform- and language-agnostic.

REST API Resources

The concept of a “resource” is the cornerstone of REST. It is convenient to think about them as either collections of entities, or individual entities.

Use Nouns in Resource Names

When naming REST API resources, use nouns and avoid verbs.

For example:

  • /post for the resource that returns a collection of blog posts,
  • /me for the resource that returns the information about the current user.

Sometimes a REST API needs to provide functionality that produces some output without actually exposing any entity, such as translation or currency conversion. You can still use nouns in such resource names. For example, /translation for a resource that returns translations from one language to another. Or /amount for the resource that converts amounts between currencies.

I believe it is always possible to replace a verb in a resource name with a noun. I’ll share a few ways how to achieve that a bit later.

Avoid Deeply Nested Resources

Sometimes resources have to be nested. For example, a nested resource that represents blog post comments could be /posts/r83fj3/comments. When working with nested resources, it is best to avoid deep nesting. Two levels like in the example is enough in most scenarios.

Use Non-Sequential Resource Ids

It is best to use non-sequential (maybe random) ids with resources. That will protect your data from enumeration attacks and will also make things like merging datasets simpler if you find that two of your resources have to become one while preserving the ids of the entities. UUIDs or random strings are good enough. For example, /posts/r83fj3.

api api-development rest apis

Bootstrap 5 Complete Course with Examples

Bootstrap 5 Tutorial - Bootstrap 5 Crash Course for Beginners

Nest.JS Tutorial for Beginners

Hello Vue 3: A First Look at Vue 3 and the Composition API

Building a simple Applications with Vue 3

Deno Crash Course: Explore Deno and Create a full REST API with Deno

How to Build a Real-time Chat App with Deno and WebSockets

Convert HTML to Markdown Online

HTML entity encoder decoder Online

An API-First Approach For Designing Restful APIs | Hacker Noon

I’ve been working with Restful APIs for some time now and one thing that I love to do is to talk about APIs.

A Simple Guide to API Development Tools

APIs can be as simple as 1 endpoint for use by 100s of users or as complex as the AWS APIs with 1000s of endpoints and 100s of thousands of users. Building them can mean spending a couple of hours using a low-code platform or months of work using a multitude of tools. Hosting them can be as simple as using one platform that does everything we need or as complex as setting up and managing ingress control, security, caching, failover, metrics, scaling.

What is REST API? An Overview | Liquid Web

What is REST? The REST acronym is defined as a “REpresentational State Transfer” and is designed to take advantage of existing HTTP protocols when used

A Simple Guide to Planning API Roadmaps

APIs - the current “big thing” - offer the opportunity for modern organizations to unlock new and lucrative business models. The article below covers some tips on how to spin the API flywheel and leverage its possibilities. 

54% of Developers Cite Lack of Documentation as the Top Obstacle to Consuming APIs

APIs are perceived as reliable—more than half of respondents stated that APIs do not break, stop working, or materially change specification often enough to matter.