10 Essential API Design Rules for Consistent Backend Services

Introduction

Ever been frustrated by a poorly designed API? In the world of micro‑services, consistent backend API design is essential. This article outlines short, sweet best practices to keep your APIs clean and reliable.

Key Terminology

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

Collection: a set of resources, e.g., a user list.

URL: the location identifier for a resource or collection, e.g., /user.

1. Use kebab‑case for URLs

Incorrect:

/systemOrders

/system_orders

Correct:

/system-orders

2. Use camelCase for parameters

Incorrect:

/system-orders/{order_id}

/system-orders/{OrderId}

Correct:

/system-orders/{orderId}

3. Use plural names for collections

Incorrect:

GET /user

GET /User

Correct:

GET /users

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

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

GET /shops/:shopId

GET /category/:categoryId

5. Keep verbs out of resource URLs

Incorrect:

POST /updateuser/{userId}

GET /getusers

Correct (use HTTP methods):

PUT /user/{userId}

6. Use verbs only for non‑resource actions

Example:

POST /alarm/245743/resend

7. Use camelCase for JSON properties

Incorrect:

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

Correct:

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

8. Monitoring endpoints

Implement /health, /version, and /metrics endpoints. /health returns 200 OK, /version returns the API version, and /metrics provides performance data.

9. Use simple sequential versioning

Prefix URLs with a version like v1 or v2:

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

10. Include total resource count in responses

Correct response format:

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

11. Accept limit and offset parameters for pagination

GET /shops?offset=5&limit=5

12. Provide a fields query parameter to limit returned data

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

13. Never place authentication tokens in URLs

Incorrect: GET /shops/123?token=abc123 Correct: send tokens in the Authorization header.

14. Validate content‑type

Content-Type: application/json

15. Use proper HTTP methods for CRUD operations

GET – retrieve a resource.

POST – create a new resource.

PUT – replace an existing resource.

PATCH – partially update a resource.

DELETE – remove a resource.

16. 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.

POST /shops – create a new shop.

17. Enable CORS for public APIs

Support the * origin and enforce OAuth token validation.

18. Enforce HTTPS everywhere

Use TLS for all endpoints, callbacks, push notifications, and webhooks.

19. Proper error handling

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

20. Golden rules

Flat is better than nested.

Simplicity beats complexity.

Strings are preferable to numbers.

Consistency outweighs customization.

Translator: Mr.lzc, software engineer, DevOpsDays, HDZ Shenzhen core organizer, currently at Huawei focusing on cloud computing, K8s, and micro‑services.