What is a REST API: the definition, and what the term has come to mean in practice
A REST API is an interface that lets one system read and change another system's data over HTTP, by sending requests to addressable URLs using standard methods such as GET, POST, PUT, PATCH and DELETE, and receiving structured responses, usually in JSON. Your system asks. Their system answers.
What does REST stand for?
Representational State Transfer. Roy Fielding defined it in chapter 5 of his 2000 dissertation at UC Irvine, Architectural Styles and the Design of Network-based Software Architectures, as an architectural style rather than a protocol or a specification.
The style is a set of constraints: client and server separated, communication stateless, responses labelled cacheable or not, a uniform interface, a layered system, and optional code on demand. Stateless carries the most practical consequence. Each request holds everything needed to serve it, which is what lets you put twenty identical servers behind a load balancer.
Industry usage has drifted from the dissertation. What almost everyone means by a REST API today is a resource oriented HTTP and JSON interface, usually without hypermedia controls in the responses, and Fielding himself has objected to that usage. Worth knowing the gap exists.
How does a REST API work?
The building block is the resource: a thing with a name, addressed by a URL. The method says what to do to it.
- GET reads. Safe, meaning it should never change state.
- POST creates or submits. Not idempotent: sending it twice usually creates two things, which is why retry logic around POST needs an idempotency key.
- PUT replaces a resource at a known URL. Idempotent, because the second call leaves the same final state. RFC 9110 defines the term as multiple identical requests having the same intended effect as one.
- PATCH applies a partial update. Not defined as idempotent, and whether it is depends on how the patch is expressed.
- DELETE removes. Idempotent too: the second call may return 404, but server state is identical either way.
Status codes carry the outcome: 2xx succeeded, 4xx you sent something wrong, 5xx they failed. That split decides your retry policy. Retrying a 400 never works. Retrying a 503 usually does.
Two details bite later. Cursor based paging survives concurrent inserts where offset based paging quietly skips or repeats rows. And versioning decides what happens when a provider changes a field, so ask about the deprecation policy before you build.
Authentication: who is calling
Every request has to prove who is calling. Two patterns dominate.
- API keys. A long lived secret in a header. Only as good as your secret handling. Keys belong in a secret manager, never in source control, never in a query string where they land in server logs, never in client side code.
- OAuth 2.0. You exchange credentials for a short lived access token and send it as a bearer token. Server to server integrations use the client credentials grant; anything acting for an end user uses the authorization code flow with PKCE. The gain over a static key is that a leaked token expires on its own.
Three habits then do most of the work. Scope every credential to the least it needs, so a reporting integration cannot delete records. Rotate on a schedule, supporting two valid credentials during the overlap. And issue separate credentials per integration, because a shared key can never be revoked without an outage somewhere you did not expect. Higher assurance setups add mutual TLS or request signing.
Rate limits: how often you may call
Providers cap request volume to protect capacity and stop one noisy client degrading everyone else. Exceed it and you get HTTP 429 Too Many Requests, defined in RFC 6585, which may carry a Retry-After header saying how long to wait.
Handling it badly is one of the most common reasons an integration falls over in production:
- Honour Retry-After when present. It is the provider telling you the answer. Guessing is worse.
- Back off exponentially, with jitter. Without a random component, every client that hit the wall retries in sync and hits it again together.
- Read the quota headers. Most APIs return remaining requests and a reset time. Throttle before the limit rather than reacting after.
- Know the shape of the limit. A token bucket allows short bursts against a sustained rate. A fixed window does not. Same number, very different behaviour on a batch job.
- Stop polling where a webhook exists. Calling every thirty seconds for a twice daily change is what consumes the quota.
REST API versus webhook: which one to reach for
An API is pulled and a webhook is pushed, and that sentence answers most design questions. Use the API when you need current state on demand, or when you are writing data into the other system. Use a webhook when you need to know about a change without asking repeatedly.
The durable pattern uses both. The webhook wakes you up, the API call fetches the record, and a scheduled sweep catches anything the webhook layer dropped. Push for timeliness, pull for truth.
REST API example: pulling a completed case
A middleware service receives a webhook: case 4471 has completed. It calls GET /v1/cases/4471 with a bearer token and gets the structured record back: answers, media references, timestamps and the integrity information behind the evidence integrity trail.
It then POSTs a claim into the insurer's core system and PATCHes the case with the claim reference, so both sides hold the same identifier. If the core system returns 429, the worker waits the interval it was given and tries again, losing nothing because the job is queued rather than tied to the original request.
That is the integration surface any modern remote inspection software is expected to offer, and why Venta Capture, a product of VentaVid, exposes a REST API alongside its webhooks. It is also why low code platforms include a generic API step: whatever the connectors miss, an HTTP call fills.