Designing a Rest API Part 1: Naming Syntax

This article is the first in a series of great takeaways on how to craft a well-designed REST API. As you read through the articles you will learn how to form an API in a way that is easy to expand, document, and use.

The articles will not cover implementation details(eg. no code samples). Still, any suggestions given here will be possible to implement in any proper framework like Spring Boot, .Net Core MVC, NestJS, and others.

Also, these series will only cover JSON as the envelope for data. REST APIs can use any data format they like, but it is outside of the scope of this series. The things you can expect to get from these articles are related to REST APIs with JSON as the data format and will cover these subjects:

1. Naming conventions (This article)
2. Recognizable design patterns
3. Idempotency (Future article)
4. Paging and sorting (Future article)
5. Searching (Future article)
6. Patching (Future article)
7. Versioning (Future article)
8. Authentication (Future article)
9. Documentation (Future article)

That's the overview. Let's get started looking at the naming conventions and let's start with Name Casing Conventions.

Name Casing Conventions

First, we will cover the use of casing when designing your REST API. As you probably know there are quite a few common casing conventions around, some of which are:

• PascalCase
• CamelCase
• Snake_case

More than these exist, but these are the ones most common in REST APIs. For example, you will see that Stripe’s API  uses snake_case, some of Amazon’s API uses PascalCase and Previsto’s API uses camelCase. As you traverse the many fine REST APIs out there to find inspiration, you will see that there is no de facto standard for which naming convention to use.

However - I must emphasize that camelCase does offer some benefits for APIs that are meant to be used directly in a browser application (or other JavaScript clients) because it is the same casing that is standard in JavaScript. That means if the REST API uses camelCase in its JSON, then when that JSON is parsed by JavaScript the object fields will have the casing that fits.

Example:

Imagine the following is the data received from the server.

{
    "id": "anim-j95dcnjf3fjcde8nv",
    "type": "Cat",
    "name": "Garfield",
    "needsFood": true
}

Then in the client code, using this can be as simple as:

fetch('https://myshop.com/animals/anim-j95dcnjf3fjcde8nv')
  .then(response => response.json())
  .then(animal => console.log(`${animal.name} needs food: ${animal.needsFood}`));

Using camelCase ensures that the fields on the object do not need to be translated into another case when parsed in JavaScript. They will immediately be in the correct case when parsed to JavaScript objects. That said, converting the case when parsing the JSON is also possible and often done if the REST API uses another case, but it is just more work on the client side.

Plural or Singular

Another question that often arises is whether to use plural or singular naming for the resources in the URLs, fx. animals or animal (Reflected in the URL as either https://myshop.com/animals or https://myshop.com/animal). It may look like a superfluous thing to consider, but in reality, making the right decision makes the API simpler to navigate.

Why Some Prefer Singular Naming

Some prefer the singular model here. They may argue that the Entity is a class called Animal in the backend which is singular. Therefore the resource should also use a singular naming of the resource, they say. The name of the resource thereby defines the type of data in the resource. That sounds like a legit reason, but it is not.

Why Plural Naming Is Almost Always Correct

According to the definition of REST on Wikipedia, a resource "encapsulates entities (e.g. files)". So the name of the resource is not the data type. It is the name of the container of entities - which usually is of the same type. Imagine for a second how you would write a piece of code that defines a "container" of entities.

// Using plural would be the correect naming 
var animals = new ArrayList<Animal>();
animals.add(new Animal());

// Using singular would not
var animal = new ArrayList<Animal>();
animal.add(new Animal());

You can look at the resource the same way. It is a container of entities just like Arrays, Lists, etc., and should be named as such. It will also ensure that the implementation in the client can reflect the resource names in its integration with the API. Consider this simplified integration as an example:

class MyShopClient {
    animals() {
        return ...;
    }
}

var myshop = new MyshopClient();
myshop.animals.findAll(); // Request to https://myshop.com/animals

Notice that the naming naturally reflects the naming of the resources on the server. Recognizable patterns like this make it easy for developers to figure out how to navigate the API.

Recognizability

Ensuring that naming and patterns are easy to recognize should be considered a quality of the API implementation. For example, using different name casing conventions or unnatural naming of resources makes it harder for the user of your API to figure out how to use it. But there is more you can do to ensure the quality of your API.

Follow along in this series as we cover multiple aspects of how to craft a REST API that is easy to expand, document, and use. In the next article, we will go into depth with how to ensure Recognizable design patterns in your API.