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/invoiceslists invoices andGET /v1/invoices/123fetches one.POST /v1/invoicescreates an invoice.PATCH /v1/invoices/123updates part of an invoice andDELETE /v1/invoices/123removes 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-Afterheader. - 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.
