Best Practices for Consistent Backend API Design

Hello everyone, I am Chen, and in the world of micro‑services, consistent backend API design is essential.

Today we will discuss some best practices you can follow, keeping it short and sweet—so buckle up and let’s go!

1. Introduce Some Terminology

All API designs follow a principle called "resource‑oriented design":

Resource : a piece of data, e.g., a user.

Collection : a group of resources, e.g., a list of users.

URL : identifies the location of a resource or collection, e.g., /user .

2. Use kebab‑case for URLs

For example, to get an order list:

Wrong:

/systemOrders
/system_orders

Correct:

/system-orders

3. Use camelCase for parameters

For example, when buying a product from a specific shop:

Wrong:

/system-orders/{order_id}

Or:

/system-orders/{OrderId}

Correct:

/system-orders/{orderId}

4. Use plural names for collections

When you want all users of the system:

Wrong:

GET /user

Or:

GET /User

Correct:

GET /users

5. URLs start with a collection and end with an identifier

To keep concepts singular and consistent.

Wrong:

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

This is bad because it points to an attribute rather than a resource.

Correct:

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

6. Keep verbs out of resource URLs

Do not use verbs in URLs; use appropriate HTTP methods instead.

Wrong:

POST /updateuser/{userId}

Or:

GET /getusers

Correct:

PUT /user/{userId}

7. Use verbs for non‑resource endpoints

If an endpoint only performs an action, a verb is acceptable. Example:

POST /alarm/245743/resend

These are not CRUD operations but specific functions.

8. Use camelCase for JSON property names

When building JSON request/response bodies, use camelCase.

Wrong:

{
  user_name: "Mohammad Faisal",
  user_id: "1"
}

Correct:

{
  userName: "Mohammad Faisal",
  userId: "1"
}

9. Monitoring endpoints

RESTful services should implement /health , /version , and /metrics endpoints.

/health : respond with HTTP 200 OK.

/version : respond with the version number.

/metrics : provide metrics such as average response time.

It is also strongly recommended to expose /debug and /status endpoints.

10. Do not use table names as resource names

Avoid using raw table names; they expose internal architecture.

Wrong:

product_order

Correct:

product-orders

11. Use API design tools

Good documentation tools include:

API Blueprint: https://apiblueprint.org/

Swagger: https://swagger.io/

Well‑documented APIs provide a better user experience.

12. Use simple numeric versions

Always version your API with a simple prefix such as v1 , v2 , etc.

Example: http://api.domain.com/v1/shops/3/products

13. Include total resource count in responses

If an API returns a list, include a total field.

Wrong:

{
  users: [ ... ]
}

Correct:

{
  users: [ ... ],
  total: 34
}

14. Accept limit and offset parameters

Always support pagination parameters in GET requests.

GET /shops?offset=5&limit=5

15. Provide a fields query parameter

Allow callers to request only necessary fields, reducing response size.

GET /shops?fields=id,name,address,contact

16. Do not put authentication tokens in URLs

Tokens in URLs can be logged; instead, send them in headers.

Wrong:

GET /shops/123?token=some_kind_of_authenticaiton_token

Correct:

Authorization: Bearer xxxxxx, Extra yyyyy

17. Validate content‑type

Never assume the request content‑type; enforce application/json when appropriate.

content-type: application/json

18. Use proper HTTP methods for CRUD

GET – retrieve, POST – create, PUT – replace, PATCH – partial update, DELETE – remove.

19. Use relationships in nested resource URLs

GET /shops/2/products – list products of shop 2

GET /shops/2/products/31 – details of product 31 in shop 2

DELETE /shops/2/products/31 – delete that product

PUT /shops/2/products/31 – update that product

POST /shops – create a new shop

20. Support CORS for public APIs

Allow "*" origins and enforce OAuth token validation.

21. Enforce HTTPS

All endpoints, callbacks, push notifications, and webhooks must use TLS.

22. Error handling

Return 4xx status codes for client errors and include detailed validation information when possible.

23. Golden rules

Flat is better than nested.

Simplicity beats complexity.

Strings are preferred over numbers.

Consistency beats customization.

That’s it—congratulations on reaching the end! I hope you learned something useful.