What a RESTful API Is
TL;DR
A REST API exposes resources over HTTP. Name those resources with nouns, use methods and status codes for their defined purpose, version breaking changes, paginate lists, return one error format, and make retries safe.
Resource
Method
Response
A RESTful API exposes named resources over HTTP. Clients send a method, a path, and sometimes a body. Servers answer with a status code and a representation, usually JSON. These REST API best practices keep that contract predictable: resource naming, methods, status codes, versioning, pagination, error formats, and idempotency.
The examples use a generic orders API. The same rules apply in any language.
Resource naming
Name the thing, not the action. Collections are plural nouns. An item lives under the collection.
A verb in the path fights the method. POST /v1/orders creates an order. POST /createOrder hides that behind a custom name and is harder to extend.
A few rules cover most APIs:
- Use lowercase paths. Separate words with hyphens when a single word is awkward, as in
/v1/shipping-addresses. - Nest a path only when the relationship is stable, as in
/v1/customers/cus_123/orders. Two levels is usually enough. - Put filters, sort, and pagination in the query string:
/v1/orders?status=open&sort=created_at. - Pick one identifier style and keep it. Opaque ids such as
ord_123do not leak a database sequence. - Pick one JSON field style,
snake_caseorcamelCase, and use it in every body. - Send timestamps as ISO 8601 strings in UTC, such as
2026-11-01T14:00:00Z. - Choose whether paths have a trailing slash, then do not serve both.
GET must not create or change resources. If the caller needs to start work, use POST.
HTTP methods
Use the method that matches the effect on the server. Clients and intermediaries already know which methods are safe to retry.
PUT sends the full representation you want stored. Repeating the same PUT leaves the resource in that state. PATCH sends a partial change. A patch such as "set status to cancelled" is idempotent. A patch such as "increment quantity by 1" is not, because a retry applies it twice.
Status codes
The status code is the machine-readable result. The body can explain it. Do not return 200 with an error object and expect clients to notice.
A successful create looks like this:
401 means "authenticate again". 403 means "this identity is not allowed". Mixing them up makes clients prompt for a password when they will never be allowed in.
Deleting an already deleted resource does not change server state, so DELETE is still idempotent if the second call returns 404. Document that choice and keep it. Some APIs return 204 both times. Either rule is fine if it never changes.
Versioning
Put the major version in the path so it shows up in logs, traces, and client code.
Keep every change inside v1 backward compatible:
- You can add a new field to a response.
- You can add an optional field to a request.
- You cannot rename or remove a field clients already use.
- You cannot change the meaning of a field, the type of a value, or the success status of an existing call.
When you must break that contract, publish /v2 and run it beside /v1. Document the sunset date. If you can, send Deprecation and Sunset headers on the old version so clients can detect it.
A header such as Accept: application/vnd.example.v1+json is a valid alternative. Path versions are easier for most clients to see and for servers to route. Pick one scheme.
Pagination
Collections grow. Do not return every row in one response.
Cursor pagination holds up when rows are inserted or deleted between pages. The client asks for a page size. The server returns that many items and a cursor that points at the next page. An absent or null cursor means there is no next page.
The cursor is opaque. Clients pass it back as they received it. They do not parse it or build their own.
limit and offset are easier to implement, and they are fine for a small collection that does not change while someone pages through it. On a live feed, offset skips rows that were inserted above the window and repeats rows that shifted up. Prefer a cursor there.
Also cap limit. A client that asks for a million rows should get the maximum you document, not a timeout.
Error formats
Use one JSON shape for every error, and use the HTTP status that matches it. Clients branch on a stable identifier. People read the message. The message can be edited. The identifier should not change once clients depend on it.
RFC 9457 problem details is a standard shape for this. Set Content-Type to application/problem+json.
type is a stable identifier. status repeats the HTTP status. detail is safe to show a caller. pointer is a JSON Pointer to the bad field. errors is an extension member, which the RFC allows, so validation problems can list more than one field.
Do not put stack traces, SQL, or secret values in this body. Log those on the server.
Idempotency
An idempotent request can be repeated without changing the outcome after the first success. GET, PUT, and DELETE should behave that way when the request body and path are the same.
POST is not idempotent. A timeout after a successful create is the usual failure: the client retries, and the server creates a second order. For any POST that creates something, charges someone, or sends a message, accept an Idempotency-Key header.
Store the key, a hash of the request, and the response you sent.
- The first request runs and stores that response, status code included.
- The same key and the same body return the stored response and do not create another order.
- The same key with a different body returns
409. - Keep the record at least as long as clients retry, often 24 hours.
The client generates the key, one key per logical operation. A retry reuses it. A new order gets a new key.
Taken together, the practices above give a client one way to list, create, read, replace, update, and delete a resource, and one way to recover when the network fails halfway through.
Questions & Answers about RESTful API
Name resources with nouns, use HTTP methods for their defined purpose, and return accurate status codes. Version breaking changes, paginate collections, use one error format, and make retries safe with idempotent methods or an idempotency key.
