APIs connect your website, mobile app, admin panel and partners to the same data. A well-designed API is predictable, secure and easy to change; a poorly designed one becomes the bottleneck for every new feature. This guide covers best practices for REST and GraphQL and how to choose between them.

REST best practices

REST organises an API around resources, such as users, orders and products, accessed with standard HTTP methods.

Use nouns and HTTP methods

  • GET /orders lists orders; GET /orders/123 fetches one.
  • POST /orders creates an order.
  • PATCH /orders/123 updates part of an order; PUT replaces it.
  • DELETE /orders/123 removes it.

Keep URLs as nouns. Avoid verbs like /getOrders or /createOrder.

Return meaningful status codes

  • 200 OK for success, 201 Created after creating a resource, 204 No Content when there is nothing to return.
  • 400 Bad Request for invalid input, 401 Unauthorized when not signed in, 403 Forbidden when signed in but not allowed, 404 Not Found, 409 Conflict for duplicate or conflicting changes, 422 Unprocessable Content for validation failures.
  • 429 Too Many Requests when rate limits are hit.
  • 500 only for genuine server errors.

Use a consistent error format

Every error should have the same shape, with a machine-readable code, a human-readable message and details about which field failed. The Problem Details standard (RFC 9457) is a good basis.

Paginate, filter and sort

Never return an unbounded list. Offer pagination (cursor-based for large or fast-changing data, page numbers for simple cases), filtering through query parameters such as ?status=paid, and sorting such as ?sort=-createdAt.

Version deliberately

Mobile apps in particular keep calling old versions for months. Version through the URL (/v1/) or a header, avoid breaking changes inside a version, and announce deprecations well in advance.

Make writes idempotent where it matters

Network retries can send the same request twice. For payments and orders, accept an idempotency key so a repeated request returns the original result instead of charging twice.

Rate limit

Protect your API from abuse and accidental overload with per-user or per-IP limits, and return the limits in response headers so clients can back off.

Authentication and authorisation

  • Use OAuth 2.0 and OpenID Connect for third-party and social sign-in.
  • Use short-lived access tokens with refresh tokens, or secure HTTP-only session cookies for browser apps.
  • Use API keys only for server-to-server access, never inside a mobile app or browser.
  • Check authorisation on every request: being signed in does not mean a user may read every order. Broken object-level authorisation tops the OWASP API Security Top 10 for good reason.

Document the API

Describe REST APIs with an OpenAPI specification. It powers interactive documentation, client code generation and contract tests, and keeps frontend and backend teams in agreement.

GraphQL best practices

GraphQL exposes a typed schema and lets clients ask for exactly the fields they need in a single request.

Design the schema around the product

Model types the way the interface uses them, with clear names and descriptions. Avoid exposing database tables directly.

Solve the N+1 problem

A query for 50 orders and each order's customer can trigger 51 database queries. Batch and cache lookups with a DataLoader-style utility.

Paginate with connections

Use cursor-based pagination, commonly the connections pattern with edges, nodes and page info, for lists.

Limit query cost

Clients can write very expensive queries. Set limits on query depth and complexity, add timeouts, and for public APIs consider persisted queries, where only pre-approved queries are allowed.

Handle errors clearly

GraphQL can return partial data with errors. Use consistent error codes in the extensions field, and model expected business errors, such as "coupon expired", as part of the schema.

Plan for caching

Because GraphQL usually uses one endpoint with POST requests, standard HTTP caching does not apply directly. Use client-side normalised caches, persisted queries over GET or server-side response caching.

REST or GraphQL?

Choose REST when:

  • The API is public or used by partners who expect standard conventions.
  • Resources map cleanly to screens and HTTP caching matters.
  • The team is small and wants the simplest option.

Choose GraphQL when:

  • Several clients (web, iOS, Android) need different shapes of the same data.
  • Screens combine data from many sources and REST would need many round trips.
  • The frontend team wants to evolve quickly without new endpoints for every screen.

Many products use both: REST for public, webhook and file-upload endpoints, and GraphQL for the app's own complex screens. For a TypeScript project where one team owns both ends, end-to-end typed RPC tools such as tRPC are another option.

Security checklist

  • HTTPS everywhere.
  • Validate and sanitise every input on the server.
  • Authorise access to every object, not just every endpoint.
  • Never return more fields than the client needs, especially personal data.
  • Rate limit, and log suspicious activity.
  • Keep dependencies updated and scan them automatically.
  • Verify signatures on incoming webhooks, for example from payment gateways.

Testing and monitoring

  • Unit tests for business logic and integration tests for each endpoint.
  • Contract tests against the OpenAPI spec or GraphQL schema.
  • Monitoring of latency, error rates and traffic per endpoint, with alerts.
  • Request IDs in logs so one request can be traced across services.

Conclusion

Good APIs are consistent, documented, secure by default and designed for change. REST remains the simplest choice for most public and straightforward APIs, while GraphQL shines when many clients need flexible data. If you are planning a platform with web and mobile clients, talk to us about the right design for it.