Are you setting REST API Endpoints correctly?

Are you setting your API endpoints right? It’s often when we are setting endpoints for our APIs, we come across situations where we are not sure whether to write in plural form or singular. Should we use underscores or hyphens? How to mention IDs? For an API that’s creating a resource should we use /resource/create? And many more. So let’s take a deep dive into the naming convention for REST APIs. Here we’ll be covering:

• Endpoints
• Methods
• Versioning

Endpoints

Let’s kick things off by going through some REST API naming conventions.

Resources as Nouns

REST APIs should allow you to manipulate a resource by using one of the main HTTP methods. The REST URIs should not indicate any kind of CRUD operations. They should refer to a resource instead of an action/verb. Whenever possible, use plural forms of the nouns only, unless they are singleton resources.

Good Examples:

• https://api.website.com/v1/store/products
• https://api.website.com/v1/store/customers
• https://api.website.com/v1/store/discounts

Bad Examples:

• https://api.website.com/v1/store/createproducts
• https://api.website.com/v1/store/updatecustomers
• https://api.website.com/v1/store/getdiscounts

Hierarchy

The hierarchy between resources and collections is defined by the use of slashes.

“As with everything in the craft of Software Development, naming is critical to success”

Good Example:

• https://api.website.com/v1/item/store

Bad Example:

• https://api.website.com/v1/store/items

Hyphens

It’s widely accepted that reading hyphens ( first-name ) is more clearer and user-friendly than reading underscores ( first_name ). So, whenever a REST API endpoint contains multiple words, it’s always better to use hyphens in place of underscores. Plus, there’s an angle here from an SEO point of view as well. It is recommended to use hyphens as it helps bots to identify the concepts in the URL more easily. And an underscore between two words is as whole considered a word, whereas using hyphens is considered as two separate words.

Good Example:

• https://api.website.com/v1/store/inventory-management/active-orders

Bad Example

• https://api.website.com/v1/store/inventory_management/active_orders

Methods

We now know to not use verbs in our REST API endpoints, but it begs the question that how to specify the verb then. For this, we have HTTP Methods to the rescue. HTTP Methods are the verbs which indicate the kind of operation the API might be executing.

HTTP Methods:

• GET corresponds to the “Read” operation of a resource or a collection.
• POST corresponds to the “Create” operation of a resource or a collection.
• PUT corresponds to the “Update” operation of a resource or a collection.
• DELETE corresponds to the “DELETE” operation of a resource or a collection.

There are a total of 39 HTTP Methods but GET, POST, PUT & DELETE are the most commonly used and basic methods. We will be covering all the HTTP methods and their use cases in a separate blog.

Versioning

It’s always better to version your APIs. The same URLs can be consumed without having to do any major changes in the REST API endpoints. API endpoints should never be invalidated as this might have unforeseen consequences for the applications consuming them.

Examples:

• https://api.website.com/v1/store/items
• https://api.webiste.com/v2/store/employees

Key Points

• Use Nouns to represent resources.
• Avoid using verbs in the REST API endpoints.
• Do not use underscores (`_`) in an endpoint. Rather use hyphens (`-`).
• Use Queries to filter, sort or limit an API collection.
• Never add file extensions to the URLs. If you want to specify the type of content, then use the `Content-Type` header.
• Always prefer using lowercase letters in the REST API endpoints.
• Do not put trailing slashes (`/`) in the Rest APIs endpoints. They add no semantic value and can be confusing.
• Pick simple names. If done correctly, API endpoints will become very easy for any developer to remember or guess.