QA ENGINEERING GUIDE

REST API Best Practices

Design and testing considerations for building and verifying REST APIs.

REST principles

REST treats the system as a set of resources, each identified by a URL and manipulated with HTTP methods. Statelessness means each request carries everything the server needs to process it, with no reliance on server-side session memory.

When these principles hold, an API is cacheable, testable and predictable. Intercept any request in isolation and you can understand it fully without replaying earlier calls.

URL and resource naming

Name resources as nouns, not verbs: /orders, not /getOrders. Use plural table-like names for collections and nest sub-resources sparingly, such as /users/42/orders.

Keep hierarchy shallow, avoid verbs in the path and use what the operation is over the resource itself. Simple, consistent naming makes the API self-documenting and easier to assert against.

HTTP methods and status codes

Each verb expresses an intent: GET reads, POST creates, PUT replaces, PATCH partially updates, DELETE removes. Reusing verbs incorrectly, such as POST for updates, breaks contracts and makes tests misleading.

Status codes must match that intent. Creation returns 201, validation failure 400, unauthorized 401, forbidden 403, not found 404 and server failure 500. Testers should verify the status code and that its semantics match the method used.

Request and response formats

JSON is the dominant format, and it should be shaped by content negotiation: clients request a format and the server honors it. Keep field names consistent, use ISO 8601 for dates and always return a uniform envelope for errors.

Verify that the server returns the requested Content-Type, rejects unsupported ones and that a single format is used across every endpoint. Mixed formats are a contract bug that breaks clients silently.

Pagination, filtering and sorting

Collection endpoints should paginate instead of returning every row. Common patterns are offset/limit and cursor-based pagination, each returning total counts and metadata in a stable shape.

Support predictable query parameters for filtering and sorting, such as ?status=active and ?sort=-created_at. Tests should check default page sizes, the last page behavior, invalid sort keys and that filtered results honor every condition.

Error handling and error shape

Errors are part of the contract. A well-designed API returns a structured body with an error code, a human message and a request identifier, not an empty 500.

Document error codes in the contract and use one envelope for all failures. Test each error response for shape, not just status, and confirm that neither sensitive data nor stack traces leak in the body.

Versioning

APIs evolve, and clients must not break on change. The most common approaches are a version in the URL path such as /v2/orders or a version header negotiated at request time.

Testers should verify that old versions still route correctly, new clients reach the latest version and that the versioning mechanism is consistent across all endpoints and error responses.

Idempotency

An idempotent operation produces the same result no matter how many times it is executed. GET, PUT and DELETE should be naturally idempotent, while POST needs an idempotency key to protect against duplicate submissions.

Repeat the same payment or order request twice and the second call must not create a second record. This single test prevents the most expensive bugs in commerce and integrations.

What testers should verify

For every endpoint, confirm the method semantics, status code and response body together. Check that authentication is required where designed, validation rejects malformed input cleanly and pagination returns complete, ordered data.

Also verify idempotency for writes, version stability across iterations and that error responses never leak internals. Treat the API contract as a test oracle and hold every change to it.