Git Branching Strategy: Trunk-Based vs GitFlow for Teams
Trunk-based development or GitFlow? Compare Git branching strategies for outsourced and offshore teams, with a decision table and rules that keep releases safe.
Practical REST API design best practices: naming, versioning, pagination, error handling and security, so your web and mobile apps scale without rework.
An API is a promise. Once a mobile app, a partner integration or a customer script depends on it, every change carries a cost. That is why API design deserves more attention at the start of a project than almost any other technical decision. A poorly designed API slows every feature built on top of it, while a consistent one makes new screens, new clients and new developers easy to add.
This guide covers the REST API design practices we see matter most when product teams build or commission a backend.
REST works best when URLs describe things, and HTTP methods describe what you do to them.
GET /orders lists orders, GET /orders/42 fetches one.POST /orders creates an order.PUT or PATCH /orders/42 updates it; DELETE /orders/42 removes it.Avoid verb-style endpoints such as /getOrderById or /cancelOrderNow. When an action genuinely does not fit a resource, model it as a sub-resource (for example POST /orders/42/cancellation) and stay consistent about it across the whole API.
Pick one convention for naming and stick to it: plural nouns, lowercase, hyphens in paths, and one casing style for JSON fields.
Clients should be able to react to a response without parsing prose.
| Situation | Typical status |
|---|---|
| Resource created | 201 Created |
| Validation failed | 400 or 422 |
| Not authenticated | 401 |
| Authenticated but not allowed | 403 |
| Resource not found | 404 |
| Rate limit exceeded | 429 |
| Server fault | 500 range |
Return errors in one predictable shape, with a machine-readable code, a human-readable message and, for validation problems, the field that failed. A single error format saves every front-end and mobile developer from writing special cases.
Any endpoint that returns a list will eventually return too many items. Add pagination from day one, because retrofitting it breaks existing clients.
?page=2&limit=50) is simple and fine for small, stable data sets.?after=<token>) performs better and stays consistent for large or fast-changing data, such as feeds and activity logs.Set a sensible default and a maximum page size, and document both. Offer filtering and sorting through query parameters rather than creating a new endpoint for each combination.
You will change the API. The question is whether you can do it without breaking people. Common approaches:
/v1/orders): the most visible and easiest to route, cache and debug.Whichever you choose, prefer additive changes within a version: new optional fields and new endpoints are safe, while removing or renaming fields is not. Publish a deprecation policy, give clients notice, and keep old versions running for an agreed period. Mobile apps matter most here, because users do not all update at once, so old app versions will call your API for months.
Networks fail, and mobile connections fail more often. If a client times out after sending POST /payments, it will retry. Support idempotency keys on operations that create or charge something, so a repeated request returns the original result instead of creating a duplicate. PUT and DELETE should already be idempotent by design.
For a broader view of securing the client side, see our mobile app security checklist.
An API without documentation is an API nobody can use confidently. Describe it with an OpenAPI specification, which can generate interactive docs, client libraries and mock servers. Treat the spec as the source of truth and test against it, so the contract between front end and back end cannot drift silently. Automated checks belong in your pipeline alongside unit tests; our guide to CI/CD with GitHub Actions shows one way to wire that in.
Good API design is cheaper at the start than at any later point. If you need a backend that web and mobile clients can rely on, our web development services cover API design, implementation and documentation, and our engineers can also work with your existing team. Get in touch to discuss your project.
Trunk-based development or GitFlow? Compare Git branching strategies for outsourced and offshore teams, with a decision table and rules that keep releases safe.
Monorepo or polyrepo? Compare code repository strategies for web, mobile and backend products, with a decision table and tips for outsourced teams.
How to version and retire APIs without breaking clients: versioning options, breaking-change rules, sunset policies and a checklist for outsourced teams.
Tell us about your platform, your product idea or the systems you want to modernise. Someone from our Chennai engineering team will get back to you personally.