Good APIs are not an accident. They come from consistent decisions, applied across every endpoint, every service, and every project. Over the past few years we have built APIs for SaaS products, internal tools, and customer-facing apps. Along the way we have learned what works, and what creates pain later. This is the checklist we use on every project, and the one we recommend to founders who are starting a new product.
1. Design the API before you build it
We start every API with a design document, not with code. We list the resources, the endpoints, the request and response shapes, and the error cases. This forces us to think about the API as a product, not as an afterthought. It also makes it easier to get feedback from the team, and from clients, before we write a line of code.
2. Use consistent naming and structure
We use REST for most of our APIs, and we keep the naming consistent. Resources are plural nouns, like /users and /projects. Actions are HTTP methods, not verbs in the URL. We do not mix styles. If you use /users in one place, do not use /getUser in another. Consistency makes an API easier to learn, and easier to use. We explain when REST is the right choice, and when GraphQL fits better, in our guide to REST versus GraphQL.
3. Version from day one
We version our APIs from the first release. We use /v1 in the URL, and we never break an existing version. When we need to change something, we release a new version, and we give clients time to migrate. This sounds obvious, but many teams skip it, and then they pay for it later when they need to change an endpoint and cannot.
4. Return useful errors
An API that returns "something went wrong" is not helpful. We return structured errors, with a code, a message, and, when it helps, a link to the documentation. We use standard HTTP status codes, and we keep the error format the same across every endpoint. Good errors save hours of debugging, for us and for the developers who use our APIs.
5. Authenticate and authorise properly
We use token-based authentication, usually JWT, and we check permissions on every endpoint. We do not rely on the frontend to hide things a user should not see. If a user should not access a resource, the API returns a 403, not an empty list. Security is not a feature you add later. It is part of the design.
6. Paginate, filter, and sort
Any endpoint that returns a list should support pagination, filtering, and sorting. We use cursor-based pagination for large lists, and offset-based pagination for smaller ones. We document the parameters, and we set sensible defaults. A list endpoint without pagination is a bug waiting to happen.
7. Document as you go
We write documentation as we build, not after we finish. We use OpenAPI to describe our endpoints, and we generate client libraries from the spec. This keeps the docs in sync with the code, and it makes onboarding new developers much faster. If an endpoint is not documented, we treat it as not done.
8. Test the contract, not just the code
We test our APIs at the contract level. We check that the response shape matches the spec, that errors are returned correctly, and that authentication works as expected. Unit tests are not enough. If the API changes in a way that breaks a client, the tests should catch it before the client does.
9. Rate limit and monitor
We rate limit every public API, and we monitor usage, latency, and errors. We set alerts for spikes, and we review the logs regularly. Rate limiting protects the API from abuse, and monitoring tells us when something is wrong before our users do.
10. Keep it simple
The best API is the simplest one that does the job. We do not add endpoints we do not need, and we do not over-engineer. If an endpoint can be simple, we keep it simple. Complexity is a cost, and it is paid by every developer who uses the API.
The checklist in practice
We apply this checklist to every project, from a small internal tool to a large SaaS product. It takes a little more time up front, but it saves a lot of time later. The APIs we build are easier to use, easier to maintain, and easier to extend. If you are building a new product, start with this checklist, and you will avoid most of the mistakes we made early on.
For a broader view of how we think about architecture, see our guide to monolith versus microservices.
The bottom line
Good API design is not about following a trend. It is about making consistent, thoughtful decisions, and sticking to them. Use this checklist on your next project, and your API will be better for it.
If you want help designing or building your API, book a free strategy call and we will talk through your project.
Top comments (0)