Aadhvika.io
Software ArchitectureWritten by Aadhvika Team

Designing REST APIs Developers Love: Versioning, Pagination and Errors

A good API is a product. Learn the conventions for resource naming, versioning, cursor pagination, error formats and rate limiting that make REST APIs easy to adopt and maintain.

REST APIAPI DesignBackend
API request and JSON response panels showing a GET call, status codes, cursor pagination and versioning

For many products, the API is the product. Partners integrate with it, mobile apps depend on it and your own frontend is built on it. Once developers start using an API, every change you make can break someone's application, so the conventions you choose early matter enormously. Here are the design decisions we make when building REST APIs for SaaS products.

Name resources, not actions

Model your API around nouns (resources) and let HTTP methods express the action:

  • GET /v1/invoices lists invoices and GET /v1/invoices/123 fetches one.
  • POST /v1/invoices creates an invoice.
  • PATCH /v1/invoices/123 updates part of an invoice and DELETE /v1/invoices/123 removes it.

Use plural nouns, keep naming consistent (snake_case or camelCase, never both) and nest resources only one level deep, such as /v1/customers/42/invoices.

Use HTTP status codes correctly

  • 200 / 201 / 204: success, created, and success with no content.
  • 400: the request is malformed, and 422 means validation failed.
  • 401 / 403: not authenticated versus not allowed.
  • 404: resource not found, and 409 means a conflict such as a duplicate.
  • 429: rate limit exceeded, ideally with a Retry-After header.
  • 5xx: something failed on your side.

Version from day one

Put the major version in the URL (/v1/) or in a header. Only increment it for breaking changes, and prefer additive changes such as new optional fields, which do not break existing clients. When you do retire a version, announce it early, publish a migration guide and use Deprecation and Sunset headers.

Paginate with cursors

Offset pagination (?page=2) is easy but becomes slow on large tables and can skip or repeat records when data changes between requests. Cursor-based pagination is more reliable: return an opaque cursor with each page and let the client send it back to get the next one.

{
  "data": [ ... ],
  "next_cursor": "eyJpZCI6MTIzfQ",
  "has_more": true
}

Return consistent, helpful errors

Every error should use the same structure, with a stable machine-readable code and a human-readable message, so clients can handle problems programmatically.

{
  "error": {
    "code": "validation_failed",
    "message": "Email address is invalid.",
    "field": "email",
    "request_id": "req_8f2c1a"
  }
}

Make writes safe with idempotency

Network failures cause clients to retry. Accept an Idempotency-Key header on POST requests so a retried request creates the resource only once. This is essential for payments, orders and any operation with side effects.

Protect the API

  • Authenticate with OAuth 2.0 or API keys sent in the Authorization header, never in URLs.
  • Apply rate limits per key or tenant and return the limit headers so clients can back off gracefully.
  • Validate all input on the server and restrict responses to the fields a caller is allowed to see.
  • Always use HTTPS.

Document it like a product

Publish an OpenAPI specification and generate interactive docs, code samples and SDKs from it. Include a quick-start that gets a developer to their first successful request in minutes. A sandbox environment with test keys makes adoption even faster.

Conclusion

Great APIs are predictable. Consistent naming, clear errors, safe retries and careful versioning let other developers build on your platform with confidence, and let you keep evolving it without breaking anyone.

FAQ

Frequently Asked Questions

Offset pagination is fine for small, stable lists. For large or frequently changing data, use cursor pagination, which is faster and avoids skipped or duplicated records.

Ready to build your digital product?

Share your idea and get a scoped estimate with a realistic timeline — not a sales sequence.

  • Free scoped quote
  • Fixed price, no surprises
  • You own the code
  • Reply in 1 business day
Chat on WhatsApp