API Design Basics: Naming, Versioning, Errors and Pagination

An API is a product for developers. Whether it powers your own mobile app, connects to a partner's system or lets a client's website pull data from your platform, the people using it judge it by how easy it is to understand and how predictably it behaves. A confusing API leads to bugs, support requests and slow integrations.

You do not need to follow every academic rule of REST to build a good API. Consistency matters more than perfection. This guide covers practical conventions for naming, methods, errors, pagination and versioning that work well for most small teams.

Name Resources Clearly and Consistently

Most web APIs are organised around resources, the things your system manages, such as customers, orders or bookings. Good naming makes the API almost self-explanatory:

• Use nouns for resources and plural names: /orders, /orders/123.
• Nest only when the relationship is clear: /customers/45/orders.
• Pick one naming style for fields, such as snake_case or camelCase, and use it everywhere.
• Use the same field names for the same concepts across endpoints, such as always created_at, never a mix of created, date and timestamp.
• Return dates in a standard format such as ISO 8601 with a time zone.

If you are deciding between styles, our comparison of REST vs GraphQL explains the trade-offs.

Use HTTP Methods and Status Codes Properly

HTTP already has a vocabulary that developers understand. Using it correctly means less documentation and fewer surprises:

1. GET reads data and should never change anything.
2. POST creates a new resource or triggers an action.
3. PUT or PATCH updates an existing resource, fully or partially.
4. DELETE removes a resource.

Return status codes that match what happened: 200 for success, 201 when something was created, 400 for invalid input, 401 when authentication is missing, 403 when the user is not allowed, 404 when a resource does not exist, 409 for conflicts, 422 for validation errors if you prefer it, 429 for rate limits and 500 for unexpected server errors. Never return 200 with an error hidden in the body; it breaks client error handling.

Make Errors Helpful and Consistent

Errors are where developers spend most of their integration time, so design them carefully. Use one error format for the whole API, for example an object containing a machine-readable code, a human-readable message and, for validation errors, the specific fields that failed.

Good error messages tell the developer what went wrong and how to fix it: "phone must be in international format, such as +60123456789" is far better than "invalid input". At the same time, do not leak internal details such as stack traces or database errors, which can expose security weaknesses. Our guide to API security basics covers related protections like rate limiting.

Tip: write your API documentation and a few example requests before you build the endpoints. If an endpoint is awkward to describe, it will be awkward to use, and changing the design is cheapest before any code exists.

Paginate, Filter and Sort

Any endpoint that returns a list will eventually return too much data. Build pagination in from the start:

• Offset pagination using page and limit parameters is simple and fine for small datasets and admin screens.
• Cursor pagination using an opaque token for the next page performs better on large or frequently changing datasets.
• Set a sensible default and maximum page size so one request cannot overload your server.
• Return information the client needs to fetch the next page, such as a next cursor or total count where practical.

Offer simple filtering and sorting through query parameters, such as ?status=paid&sort=-created_at, using the same conventions across endpoints.

Version and Document Your API

Once other systems depend on your API, changing it can break them. Versioning gives you room to improve without surprising anyone. A common approach is a version in the URL, such as /v1/orders; others use headers. Whatever you choose, avoid breaking changes within a version. Adding new optional fields is usually safe; removing or renaming fields, or changing their meaning, is not.

Document every endpoint with its parameters, example requests and responses, and error codes. Specifications like OpenAPI let you generate interactive documentation and client libraries. Announce deprecations early and give integrators reasonable time to move.

FAQ

Should I use REST or GraphQL for a small project?

REST is simpler to build, cache and debug, and fits most small projects. GraphQL helps when clients need flexible queries across many related resources.

Do internal APIs need this much care?

Yes, in a lighter form. Your future self and new team members are users too, and internal APIs often become external later.

How do I handle API keys for partners?

Issue separate keys per partner, allow rotation and revoke keys that are no longer used. Never put secret keys in front-end code.

A well-designed API saves hours for everyone who touches it. Be consistent, use HTTP the way it was intended, make errors useful and treat documentation as part of the product.