REST API Design Best Practices for Indian Engineers 2026

Resources, not actions: REST URLs identify resources (nouns), not actions (verbs). HTTP methods express the action.

Good:

• GET /users/123: retrieve user 123
• POST /users: create a new user
• PUT /users/123: replace user 123 entirely
• PATCH /users/123: partially update user 123
• DELETE /users/123: delete user 123

Bad: GET /getUser?id=123, POST /createUser, POST /deleteUser

Nesting for relationships: Use nested resources for relationships, but limit to 2 levels:

• GET /orders/456/items: get items for order 456
• AVOID: GET /users/123/orders/456/items/789/reviews: too deep, better as GET /reviews?itemId=789

Plural nouns: Always use plural: /users not /user, /products not /product.

Kebab-case for multi-word paths: /payment-methods not /paymentMethods or /payment_methods.

Query params for filtering, sorting, and pagination: GET /products?category=electronics&sort=price_asc&page=2&limit=20

Authentication: what Indian companies use:

• Bearer tokens (JWT): Most common. Authorization: Bearer <token> header. Stateless: server validates the token without a database lookup.
• API keys: For server-to-server (merchant to Razorpay). Passed as header X-API-Key or as query param (less secure).
• OAuth 2.0: For third-party access (Google sign-in, accessing another user's data). Complex but standard.

API versioning: three approaches:

• URL versioning: /v1/users: simple, visible, easy to route. Most common at Indian companies.
• Header versioning: Accept: application/vnd.api+json;version=2: cleaner URLs, harder to test in browser.
• Query param versioning: /users?version=2: easy to test, messy URLs.

Error handling: consistent error response format: ```json { "status": 400, "code": "VALIDATIONERROR", "message": "The email field is invalid.", "details": [{ "field": "email", "issue": "must be a valid email address" }], "requestId": "reqabc123" } ``` Key principle: Always include a machine-readable error code (not just the HTTP status), a human-readable message, and the requestId for debugging.

Pagination: two approaches:

• Offset pagination: ?page=2&limit=20. Simple to implement but slow for large offsets (database must scan and skip). Do not use for large tables.
• Cursor-based pagination: ?cursor=eyJpZCI6MTIzfQ&limit=20. Uses an opaque cursor (encoded last item position). Efficient even at large offsets. Instagram, Twitter, and Razorpay's APIs use cursor pagination for feeds and transactions.

Rate limiting: how to communicate limits: Include rate limit information in response headers:

• X-RateLimit-Limit: 100
• X-RateLimit-Remaining: 85
• X-RateLimit-Reset: 1722470400 (Unix timestamp when limit resets)

Return 429 Too Many Requests with a Retry-After header when the limit is exceeded.

Idempotency: critical for payment APIs: For POST requests that should not be processed twice (payment, order creation), accept an Idempotency-Key header. If the same key is sent again within a time window, return the cached response of the first request. Prevents double-charges. Required by Razorpay, Stripe, and all serious payment API providers.

API documentation: Every API should be documented in OpenAPI (Swagger). Interview candidates who mention OpenAPI/Swagger in system design discussions demonstrate production-API awareness.