22 Best Practices to Take Your API Design Skills to the Next Level

Practical advice for designing REST APIs

Photo by Andrea Piacquadio from Pexels

Ever get frustrated with a horrible API where everything’s a guessing game? Well, I have.

In this world of microservices, a consistent design for your backend API is imperative.

Today, we’ll talk about some best practices to follow. We’ll keep it short and sweet — so buckle up!

First, Some Terminology

Any API design follows something called Resource Oriented Design It consists of three key concepts

• Resource: A resource is a piece of data, For example, a User.
• Collection: A group of resources is called a collection. Example: A list of users
• URL: Identifies the location of the resource or collection. Example: /user

1. Use kebab-case for URLs

For example, if you want to get the list of orders.

Bad:

/systemOrders or /system_orders

Good:

/system-orders

2. Use camelCase for Parameters

For example, if you want to get products from a particular shop.

Bad:

/system-orders/{order_id} or /system-orders/{OrderId}

Good:

/system-orders/{orderId}

3. Plural Name to Point to a Collection

If you want to get all the users of a system.

Bad:

GET /user or GET /User

Good:

GET /users

4. URL Starts With a Collection and Ends With an Identifier

If want to keep the concept singular and consistent.

Bad:

GET /shops/:shopId/category/:categoryId/price

This is bad because it’s pointing to a property instead of a resource.

Good: