What is a REST API?

REST (Representational State Transfer) is an architectural style for building web services. A REST API exposes resources (data entities like users, products, orders) via URLs and uses HTTP methods to define what operation to perform on them.

REST is not a protocol — it is a set of constraints. An API that follows these constraints is called "RESTful".

HTTP Methods and CRUD Operations

REST maps the four CRUD database operations to HTTP methods:

HTTP MethodCRUDExampleResponse
GETReadGET /users/123200 + user JSON
POSTCreatePOST /users201 + created resource
PUTReplacePUT /users/123200 + updated resource
PATCHPartial updatePATCH /users/123200 + updated resource
DELETEDeleteDELETE /users/123204 No Content

REST URL Design

Good REST API URLs follow predictable patterns:

Good REST URL design GET /users → list all users POST /users → create a user GET /users/123 → get user 123 PUT /users/123 → replace user 123 PATCH /users/123 → partially update user 123 DELETE /users/123 → delete user 123 GET /users/123/orders → list orders for user 123 GET /users/123/orders/456 → get order 456 for user 123
Bad REST URL design — avoid verbs in URLs GET /getUser?id=123 ❌ use GET /users/123 POST /createUser ❌ use POST /users POST /deleteUser/123 ❌ use DELETE /users/123 GET /user_list ❌ use GET /users (plural nouns)

HTTP Status Codes for REST APIs

CodeMeaningWhen to Use
200OKSuccessful GET, PUT, PATCH
201CreatedSuccessful POST (return Location header)
204No ContentSuccessful DELETE, or update with no body
400Bad RequestMissing required fields, invalid format
401UnauthorizedNo token, expired token
403ForbiddenAuthenticated, but not allowed
404Not FoundResource does not exist
409ConflictDuplicate email, version conflict
422Unprocessable EntityValidation errors
429Too Many RequestsRate limit exceeded
500Internal Server ErrorUnhandled server exception

6 REST Constraints

  1. Client-Server: UI and data storage are separated — client handles presentation, server handles data.
  2. Stateless: Each request is self-contained — no server-side session state between requests.
  3. Cacheable: Responses must indicate whether they can be cached (Cache-Control headers).
  4. Uniform Interface: Consistent resource naming, standard HTTP methods, HATEOAS (links in responses).
  5. Layered System: Client does not need to know if it is talking to the actual server, a load balancer, or a cache.
  6. Code on Demand (optional): Server can send executable code (JavaScript) to client.

REST vs GraphQL vs gRPC

FeatureRESTGraphQLgRPC
TransportHTTP/1.1+HTTP/1.1+HTTP/2
Data formatJSON/XMLJSONProtocol Buffers (binary)
Over-fetchingCommonNone (client specifies fields)None
CachingNative HTTP cachingComplexManual
Learning curveLowMediumHigh
Best forPublic APIs, CRUD appsComplex data graphs, mobileInternal microservices, high performance

💡 REST Best Practices

Use plural nouns for resources (/users not /user). Version your API (/v1/users). Return consistent error formats ({error, message, code}). Use HTTPS always. Add pagination to list endpoints. Set appropriate Cache-Control headers on GET responses.

How We Research and Update This Guide

We test the underlying formula or workflow, compare outputs with reliable references, and revise examples whenever the page content changes.

  • The workflow or formula is tested directly in the tool and compared against independent reference examples.
  • Examples are kept practical so readers can verify the result without hidden assumptions.
  • Pages are revised whenever the interface, calculation flow, or surrounding guidance materially changes.

Frequently Asked Questions — REST API