REST API definition
A REST API is a web interface that lets software systems exchange data over HTTP using the principles of Representational State Transfer. Resources such as users or orders have their own URLs, and clients act on them with standard methods like GET, POST, PUT and DELETE, usually sending and receiving JSON. REST is the most common style for web APIs.
How does a REST API work?
A client sends an HTTP request made of a method, a URL, headers and sometimes a body. The server processes it and returns a status code, headers and usually a JSON body. A request for GET /orders/4417 might return the order's status and items with status 200. Creating an order with POST /orders returns 201, a missing order returns 404 and a request without valid credentials returns 401.
- GET: read a resource or a list of resources.
- POST: create a new resource.
- PUT: replace a resource completely.
- PATCH: update part of a resource.
- DELETE: remove a resource.
REST principles
REST was defined by Roy Fielding in his 2000 doctoral dissertation as an architectural style for the web. Most APIs called RESTful follow its core ideas loosely rather than strictly, but the principles explain why REST APIs scale and cache well.
- Client-server: the interface separates the client from data storage.
- Stateless: each request carries everything needed to process it.
- Cacheable: responses say whether and how long they can be cached.
- Uniform interface: resources identified by URLs and manipulated through standard methods.
- Layered system: proxies, gateways and CDNs can sit in between transparently.
REST vs GraphQL vs gRPC
REST is simple, universally supported and works with HTTP caching, which makes it the default for public and partner APIs. GraphQL lets clients ask for exactly the fields they need in one request, which suits apps with many screens and varied data needs. gRPC uses Protocol Buffers over HTTP/2 for fast, strongly typed calls between internal services. Many systems use REST at the edge and gRPC inside.
REST API design best practices
- Use plural nouns for resources, such as /customers/42/invoices, and let methods express actions.
- Version the API, for example /v1/, and avoid breaking changes within a version.
- Paginate lists and support filtering and sorting through query parameters.
- Return consistent error bodies, such as the problem details format standardized by the IETF.
- Accept idempotency keys on POST requests that create payments or orders.
- Document the API with an OpenAPI specification and generate client SDKs from it.
- Use HTTP caching headers such as ETag and Cache-Control for read-heavy resources.
- Return 429 with a Retry-After header when clients exceed rate limits.
Securing a REST API
Authenticate every request, typically with OAuth 2.0 access tokens or signed API keys, and check authorization on every resource, not just at login. The OWASP API Security Top 10 lists the most common failures, led by broken object-level authorization, where a user can read another customer's order by changing an ID in the URL. Rate limiting, input validation, HTTPS everywhere and audit logs complete the basics.
Nexzem designs REST APIs contract-first with OpenAPI, so web and mobile teams can build against mock servers while the backend is still in progress, and automated tests check every endpoint against the published contract. This catches breaking changes before they reach any client app.