unkey
  • BlogRead product updates and insights
  • Case studiesPractical results from real deployments
  • ChangelogTrack what shipped, improved, and fixed
  • GlossaryClear definitions for API terms
PricingDocs
Discord
LoginSign Up
  • BlogRead product updates and insights
  • Case studiesPractical results from real deployments
  • ChangelogTrack what shipped, improved, and fixed
  • GlossaryClear definitions for API terms
PricingDocsDiscord
LoginSign Up
  1. Glossary
  2. /RESTful API

What a RESTful API Is

Explore with AI
Open in ChatGPTOpen in ClaudeOpen in Perplexity

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

noun path

Method

GETPOSTPUTPATCHDELETE

Response

statusbody

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.

GET /v1/orders?status=open HTTP/1.1
Host: api.example.com
GET /v1/orders/ord_123 HTTP/1.1
Host: api.example.com

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_123 do not leak a database sequence.
  • Pick one JSON field style, snake_case or camelCase, 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.

MethodPurposeSafe to retry
GETRead a representationYes
POSTCreate a resource, or start an action that is not a simple updateNo, unless you add an idempotency key
PUTReplace the resource with the request bodyYes
PATCHChange part of the resourceOnly if your patch definition is idempotent
DELETERemove the resourceYes

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.

POST /v1/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "customer_id": "cus_123",
  "items": [
    {
      "sku": "book-01",
      "quantity": 1
    }
  ]
}
PUT /v1/orders/ord_123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "customer_id": "cus_123",
  "status": "open",
  "items": [
    {
      "sku": "book-01",
      "quantity": 2
    }
  ]
}
PATCH /v1/orders/ord_123 HTTP/1.1
Host: api.example.com
Content-Type: application/json

{
  "status": "cancelled"
}

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.

StatusWhen to use it
200 OKThe request succeeded and the body is the representation
201 CreatedA resource was created. Include a Location header
202 AcceptedThe work was accepted and is not finished yet
204 No ContentThe request succeeded and there is no body
400 Bad RequestThe server could not parse the request
401 UnauthorizedCredentials are missing or invalid
403 ForbiddenThe caller is authenticated and is not allowed
404 Not FoundThe resource does not exist, or the caller must not learn that it exists
409 ConflictThe request conflicts with current state, including a reused idempotency key with a different body
422 Unprocessable ContentThe syntax is valid and the values are not acceptable
429 Too Many RequestsThe caller should slow down. Include Retry-After when you can
500 Internal Server ErrorThe server failed. Do not use this for bad client input
503 Service UnavailableThe server cannot handle the call right now

A successful create looks like this:

HTTP/1.1 201 Created
Location: /v1/orders/ord_123
Content-Type: application/json

{
  "id": "ord_123",
  "customer_id": "cus_123",
  "status": "open"
}

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.

GET /v1/orders HTTP/1.1
Host: api.example.com
Accept: application/json

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.

GET /v1/orders?limit=20 HTTP/1.1
Host: api.example.com
{
  "data": [
    {
      "id": "ord_123",
      "status": "open"
    }
  ],
  "next_cursor": "eyJpZCI6Im9yZF8xMjMifQ"
}
GET /v1/orders?limit=20&cursor=eyJpZCI6Im9yZF8xMjMifQ HTTP/1.1
Host: api.example.com

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": "https://api.example.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "quantity must be at least 1",
  "instance": "/v1/orders",
  "errors": [
    {
      "pointer": "/items/0/quantity",
      "detail": "quantity must be at least 1"
    }
  ]
}

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.

POST /v1/orders HTTP/1.1
Host: api.example.com
Content-Type: application/json
Idempotency-Key: 8f14e45f-ceea-467a-9a1a-9a5d6c1c1e11

{
  "customer_id": "cus_123",
  "items": [
    {
      "sku": "book-01",
      "quantity": 1
    }
  ]
}

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.

On this page

  1. Resource naming
  2. HTTP methods
  3. Status codes
  4. Versioning
  5. Pagination
  6. Error formats
  7. Idempotency

Turn your API stack into one workflow. Start for free, integrate in minutes, and scale when you need to.

Start for free
unkey

Build better APIs faster

© 2026 Unkey Inc. All rights reserved.

SOC 2 Type II Certified

Company

  • About
  • Careers
  • Status Page
  • Roadmap

Resources

  • Blog
  • Case Studies
  • Changelog
  • Docs
  • Glossary
  • Feature Request
  • Archive

Connect

  • X (Twitter)
  • Discord
  • Book a Call

Legal

  • Terms of Service
  • Privacy Policy
  • Trust Center