Web + mobile front ends
One back end feeds multiple clients.
What is a REST API? Resources, HTTP verbs, and contracts
A REST API is a web interface that exposes resources over HTTP using stable URLs, verbs (GET, POST, PUT, PATCH, DELETE), and representations—usually JSON. Inspired by Roy Fielding’s architectural style, it favors server-side statelessness and clear HTTP semantics. It is the most common contract between a front end, a mobile app, and a business back end.
In one sentence
A REST API lets clients and servers talk through HTTP and addressable resources.
Key points
- Resources have URIs; HTTP verbs describe the action without inventing a parallel protocol.
- The server keeps no session state between requests—each call carries needed context.
- JSON dominates payloads; status codes (2xx, 4xx, 5xx) communicate outcomes.
- OpenAPI/Swagger documents the contract for front, mobile, and partner teams.
Term at a glance
- REST API
- API REST · RESTful API · HTTP JSON API
- English term
- REST API
- Domain
- Software development
- Category
- Integration
- Level
- Intermediate
What does “REST API” mean exactly?
REST (Representational State Transfer) is a style—not a single ISO standard: resource identification, manipulation via representations, self-descriptive messages, and ideally hypermedia. In practice, “REST API” often means a well-structured HTTP JSON API, even when not every Fielding constraint is strict.
For an SME, the REST API is the hinge between the site, mobile app, ERP, or partner. Poor design (verbs in URLs, sticky sessions, opaque errors) slows every integration and raises support cost.
Security (TLS, OAuth 2.0 / JWT, rate limiting) and versioning (/v1) are as much the API product as business endpoints.
How do you design a solid REST API?
- 01
Model resources
Name business entities (customers, orders, invoices) and relations instead of scattered RPC-style actions.
- 02
Lock the contract
Request/response schemas, error codes, pagination, and filters—ideally described in OpenAPI.
- 03
Secure and observe
AuthN/AuthZ, logs, latency metrics, and quotas.
- 04
Version and evolve
Prefer backward-compatible changes; put breaking changes behind a new major version.
A concrete REST API example
A Montreal manufacturer exposes GET /v1/orders/{id} and PATCH /v1/orders/{id}/status so the customer portal and drivers’ app share the same state. JSON responses include an ETag; the mobile client skips reloading the full order when nothing changed. Support tickets asking “where is my order?” drop.
What is a REST API used for?
Partner integrations
Exchange catalogs, stock, or leads with third-party systems.
Internal automation
Scripts and ops tools consume the same endpoints as the product.
Microservices
Synchronous service-to-service calls over HTTP JSON.
Benefits and limits of REST APIs
- Mature HTTP ecosystem (caches, proxies, tooling)
- Readable URIs and verbs for teams
- Broad client support (browsers, mobile, SDKs)
- Easier docs and tests (OpenAPI, Postman)
- Over-fetch / under-fetch if resources are poorly shaped
- Less ideal for real-time than WebSocket or gRPC streaming
- Versioning and compatibility need discipline
- “REST-washing”: many HTTP APIs are not truly RESTful
How does REST differ from GraphQL?
| REST API | GraphQL | |
|---|---|---|
| Request shape | Multiple resource endpoints + HTTP verbs | One endpoint; client describes needed fields |
| HTTP caching | Natural on GET (URI, ETag) | Harder; often application-level cache |
| Learning curve | Low if you know HTTP | Schema, resolvers, dedicated tooling |
| Best fit | Stable contracts, classic integrations | Clients with highly variable data needs |
Why REST APIs matter for Quebec SMEs
As soon as a site, app, or partner must read your stock, appointments, or customers, you need a stable contract. A clear REST API lowers every integration’s cost, speeds partnerships, and avoids rebuilding the same logic in each channel.
Frequently asked questions
Is REST a protocol?
No. It is an architectural style on top of HTTP. We call it a REST API when those constraints are applied (more or less strictly).
Must it always be JSON?
JSON is the de facto default, but REST allows other representations (XML, etc.) via content negotiation.
How do we version without breaking clients?
Prefer backward-compatible additions; reserve /v2 for breaking changes and publish an end-of-support date.
Does REST replace message queues?
No. REST fits synchronous request/response; queues (or events) remain useful for async decoupling.
Related terms
Sources and references
Need to expose data to a site, app, or partner? We design documented, secure, evolvable REST APIs.
Talk about your API