Good API design best practices separate APIs that developers love from APIs that developers dread. A well-designed API reduces support tickets, speeds up integration, and creates a foundation that scales with your product. A poorly designed one generates confusion, breaking changes, and endless backward-compatibility headaches.
Table of Contents
Whether you’re building a REST API, GraphQL endpoint, or gRPC service, these API design best practices will help you ship interfaces that are intuitive, consistent, and resilient. At GTWebs, we apply these principles across every backend we build.
1. Design for the Consumer, Not the Database
The most common API design mistake is exposing your database schema directly through your endpoints. Your API is a contract with external consumers — it should model the domain from the consumer’s perspective, not mirror your internal tables.
If your database has a `user_account_records` table with 40 columns, your API shouldn’t return all 40 fields. Design response objects that contain exactly what the consumer needs. Use DTOs (Data Transfer Objects) or resource transformers to decouple your internal models from your public interface.
“`json // Bad: leaking internal structure { “usr_acct_id”: 4521, “acct_status_cd”: 1, “crt_dt”: “2026-01-15T…” }
// Good: consumer-friendly design { “id”: “4521”, “status”: “active”, “createdAt”: “2026-01-15T10:30:00Z” } “`
2. Use Consistent Naming Conventions
Pick a naming convention and enforce it everywhere. For REST APIs, the dominant convention is:
- URLs: lowercase with hyphens (`/user-profiles`, not `/userProfiles` or `/user_profiles`)
- JSON fields: camelCase (`firstName`, `createdAt`)
- Query parameters: camelCase (`?pageSize=20&sortBy=name`)
Consistency eliminates guesswork. A developer who has used one endpoint should be able to predict the shape of every other endpoint. The JSON:API specification provides a well-documented standard if you want a ready-made convention to follow.
3. Version Your API from Day One
API versioning isn’t something you add later — it’s something you need from the first release. The two most practical approaches are URL path versioning and header versioning.
URL path versioning (`/v1/users`, `/v2/users`) is the most explicit and widely adopted. It’s easy to understand, easy to route, and easy to deprecate. Header versioning (`Accept: application/vnd.api+json;version=2`) is cleaner in theory but harder to test and document.
Whichever approach you choose, commit to a deprecation policy. Give consumers at least 6-12 months of overlap between versions. Communicate deprecation timelines clearly in your documentation and through `Sunset` response headers as defined in RFC 8594.
4. Implement Proper Error Responses
Error handling reveals the quality of an API faster than anything else. Every error response should include a machine-readable code, a human-readable message, and enough context for the developer to fix the problem without contacting support.
“`json { “error”: { “code”: “VALIDATION_FAILED”, “message”: “The request body contains invalid fields.”, “details”: [ { “field”: “email”, “issue”: “Must be a valid email address.” }, { “field”: “age”, “issue”: “Must be a positive integer.” } ], “requestId”: “req_a8f3k29x” } } “`
Use appropriate HTTP status codes. 400 for validation errors, 401 for authentication failures, 403 for authorization failures, 404 for missing resources, 409 for conflicts, 422 for semantically invalid requests, and 429 for rate limiting. Never return 200 with an error body — it breaks every HTTP client’s error handling.
5. Paginate All List Endpoints
Any endpoint that returns a collection must be paginated. An endpoint that works fine with 50 records will bring your server to its knees with 50,000. Implement pagination from the start so consumers build their integrations correctly.
Cursor-based pagination outperforms offset-based pagination for large datasets. With offset pagination (`?page=500&pageSize=20`), the database must scan and discard 9,980 rows to return 20. With cursor pagination (`?after=eyJpZCI6MTAwMH0`), the query jumps directly to the right position using an indexed column.
Always include pagination metadata in your response:
“`json { “data”: […], “pagination”: { “hasMore”: true, “nextCursor”: “eyJpZCI6MTAyMH0”, “totalCount”: 15420 } } “`
6. Design Idempotent Operations
API design best practices demand that operations be safe to retry. Network failures happen. Clients will send duplicate requests. Your API must handle this gracefully.
GET, PUT, and DELETE should always be idempotent — calling them multiple times produces the same result as calling them once. POST is the exception, but you can make it idempotent by accepting an `Idempotency-Key` header. Store the key with the response, and if the same key appears again, return the cached response instead of processing the request again.
This is especially critical for payment APIs and any operation with real-world side effects. Stripe’s API popularized the `Idempotency-Key` pattern, and it’s now an industry standard.
7. Rate Limit and Communicate Limits Clearly
Every public API needs rate limiting to prevent abuse and ensure fair usage. Implement rate limiting at the API gateway level and communicate limits through standard headers:
“` X-RateLimit-Limit: 1000 X-RateLimit-Remaining: 847 X-RateLimit-Reset: 1711843200 Retry-After: 30 “`
When a client exceeds the limit, return `429 Too Many Requests` with a `Retry-After` header. Design your rate limits per endpoint, not just globally — a search endpoint might need stricter limits than a profile lookup.
8. Document with OpenAPI and Provide Examples
Documentation is part of the API, not an afterthought. Use the OpenAPI Specification (formerly Swagger) to define your API contract. Generate interactive documentation with tools like Redoc or Swagger UI. Include request and response examples for every endpoint, especially error cases.
The best API documentation includes runnable examples. Let developers paste a curl command or click a “Try It” button. Reduce the time from reading the docs to making a successful request to under 5 minutes.
Authentication and Security
Use OAuth 2.0 or API keys depending on your use case. Require HTTPS on every endpoint with no exceptions. Implement CORS policies that are as restrictive as possible. Validate and sanitize all input — never trust client data. Log all authentication failures for security monitoring.
For internal APIs, mutual TLS (mTLS) provides strong identity verification between services. For public APIs, short-lived access tokens with refresh token rotation provide the best balance of security and usability.
Testing Your API Design
Before building, write integration tests that exercise your API from the consumer’s perspective. Use contract testing tools like Pact to ensure your API doesn’t break consumer expectations. Load test your pagination and rate limiting under realistic conditions.
We’ve written more about backend architecture and API patterns on the GTWebs blog.
Ship It Right the First Time
API design best practices aren’t about perfection — they’re about reducing the cost of change. A well-versioned, well-documented, consistently designed API is cheap to evolve. A hastily designed one becomes an anchor that slows down every team that depends on it. Invest the time upfront.
Frequently Asked Questions
Should I use REST or GraphQL for my API?
Use REST when your data model maps cleanly to resources with CRUD operations and when you want maximum caching capability. Use GraphQL when clients need flexible queries across deeply nested relationships or when you want to eliminate over-fetching. Many teams use both — REST for simple endpoints, GraphQL for complex data aggregation.
How should I handle API versioning when I have breaking changes?
Use URL path versioning (e.g., /v1/users, /v2/users) for clarity. When introducing a breaking change, release the new version alongside the old one. Communicate a deprecation timeline of at least 6-12 months, add Sunset headers to the old version, and provide a migration guide.
What’s the best pagination strategy for large datasets?
Cursor-based pagination outperforms offset pagination for large datasets. It uses an opaque cursor (typically a base64-encoded primary key) instead of page numbers. This avoids the performance penalty of OFFSET in SQL and prevents issues with records being inserted or deleted between pages.
