22 Best Practices for Designing Consistent and Secure RESTful APIs

Ever been frustrated by a poorly designed API? In the world of micro‑services, consistent backend API design is essential. This article discusses 22 concise best‑practice guidelines to help you build clean, maintainable, and secure APIs.

Terminology

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

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

URL : the address that identifies a resource or collection, e.g., /user .

1. Use kebab‑case for URLs

Bad: /systemOrders or /system_orders

Good: /system-orders

2. Use camelCase for parameters

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

Good: /system-orders/{orderId}

3. Name collections with plural nouns

Bad: GET /user or GET /User

Good: GET /users

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

Bad: GET /shops/:shopId/category/:categoryId/price (points to an attribute)

Good: GET /shops/:shopId or GET /category/:categoryId

5. Keep verbs out of resource URLs

Bad: POST /updateuser/{userId} or GET /getusers

Good: PUT /user/{userId}

6. Use verbs for non‑resource actions

Example: POST /alarm/245743/resend to resend an alert.

7. Use camelCase for JSON property names

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

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

8. Monitoring endpoints

Implement /health (200 OK), /version (returns version), and /metrics (e.g., average response time). Also consider /debug and /status .

9. Avoid using raw table names as resource names

Bad: product_order

Good: product-orders

10. Use API design tools

Examples: API Blueprint (https://apiblueprint.org/), Swagger (https://swagger.io/).

11. Use simple ordinal versioning

Use v1 , v2 , etc. Example: http://api.domain.com/v1/shops/3/products

12. Include total resource count in responses

Bad: { users: [ ... ] }

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

13. Accept limit and offset parameters

Example: GET /shops?offset=5&limit=5

14. Provide a fields query parameter

Example: GET /shops?fields=id,name,address,contact to return only selected fields.

15. Do not pass authentication tokens in URLs

Bad: GET /shops/123?token=abc

Good: send token in the Authorization header, e.g., Authorization: Bearer xxxxxx .

16. Validate Content‑Type

Never assume the request content type; enforce Content-Type: application/json when appropriate.

17. Use proper HTTP methods for CRUD operations

GET – retrieve

POST – create

PUT – replace

PATCH – partial update

DELETE – remove

18. Express relationships in nested resource URLs

Examples: 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

19. Support CORS for public APIs

Allow * origins and enforce OAuth token authorization.

20. Enforce HTTPS everywhere

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

21. Proper error handling

Return appropriate 4xx status codes for client errors and consider aggregating multiple validation issues in a single response.

22. The golden rules

Flat structures are better than deep nesting.

Simplicity beats complexity.

Strings are preferable to numbers for identifiers.

Consistency outweighs custom solutions.

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