REST API

How a REST API works

REST is a set of architectural constraints. Fielding derived it by starting from the null style, a system with no constraints, and adding them one at a time, each chosen for a property such as scalability, visibility or independent evolution 1.

Five constraints matter most to anyone calling a data API.

• Client-server. The client handles the interface and the server handles data storage, so each side can change without the other 1.
• Stateless. Each request carries all the information needed to understand it and cannot rely on context stored on the server 1.
• Cache. Responses are labeled cacheable or non-cacheable, so a client can reuse an answer for an equivalent later request 1.
• Uniform interface. Resources have identifiers, clients act on them through representations, and messages describe themselves 1.
• Layered system. Proxies, gateways and firewalls can sit between client and server without changing the interface 1.

HTTP supplies the vocabulary. RFC 9110 calls a method safe when its semantics are essentially read-only, and idempotent when sending the same request several times has the same intended effect as sending it once 2. PUT, DELETE and the safe methods, GET included, are idempotent. POST is not on that list, which is why a repeated POST can create a duplicate unless the API adds its own protection 2.

Status codes carry the outcome. In RFC 9110, the 2xx class means the request succeeded, the 4xx class means the client seems to have erred, and the 5xx class means the server erred or cannot perform the request 2. A client that branches on the status code before it reads the body handles failure more predictably than one that parses every response the same way.

Many APIs labeled REST follow the first constraints closely and treat hypermedia loosely. They publish endpoints in documentation or an OpenAPI file instead of linking them from responses. That looser version is what many teams mean when they say REST, and it works well for request and response data calls.

For data enrichment, the practical shape is a request to a named endpoint with an API key in a header and a JSON body, followed by a JSON response and a status code. RichAPI follows that shape at api.richapi.ai/api/v1 with the x-api-key header on every request 3. Lookups such as enrich_profile are POST calls with a JSON body, and the free usage endpoint answers a plain request with no body 3.

What to check before building on a REST API

Six details decide how much client code a REST integration needs and how it behaves under load.

**Authentication.** Find out where the credential goes and whether one credential covers every endpoint. RichAPI expects the x-api-key header on every request 3.

**Method semantics.** Know which calls are safe to repeat. Idempotent methods can be retried after a timeout without changing the intended effect, while a repeated POST may create a second record or a second charge 2. Then check whether the provider bills failed calls. RichAPI states that failed calls are never billed 3.

**Error contract.** Map each status code to an action before writing the client. On RichAPI, 401 means a bad or revoked key, 402 means credits are exhausted, 429 carries a Retry-After header and 5xx errors should be retried with backoff 3.

**Description file.** An OpenAPI spec lets a team generate a typed client instead of writing one by hand. RichAPI publishes its spec at app.richapi.ai/api/openapi and offers a Postman collection inside the app 3.

**Caching.** Ask whether responses are cached and for how long. Fielding added the cache constraint to remove repeat interactions, and he also noted that stale cached data can reduce reliability 1. For contact records, stale answers lower data accuracy.

**Pagination and limits.** Search endpoints return pages, and every account has a request ceiling. Read both before sizing a batch job, and size workers to the steady limit rather than the burst.

Write the answers into the runbook next to the endpoint list, so the next engineer inherits the same rules instead of rediscovering them during an incident.

Example of calling a REST data API from a batch script

A growth engineer needs to enrich a list of profile URLs overnight and report the spend in the morning. The script talks to RichAPI over plain HTTP 3.

POST /api/v1/enrich_profile
  headers   x-api-key, Content-Type application/json
  body      the profile URL
  200       JSON record, 1 credit
  401       key revoked, stop and alert
  402       out of credits, pause the queue
  429       wait for Retry-After, then resume
  5xx       retry with backoff, not billed

GET /api/v1/usage
  200       credits spent per endpoint, free

The script sends one POST per profile and reads the status code before it reads the body. A 200 means a record came back and 1 credit was spent 3. A 429 tells the worker to pause for the Retry-After interval, and a 5xx goes back on the queue for a later attempt, since neither is billed 3.

Because each request is stateless and carries its own key and body, the job runs on several workers at once without a shared session 1. Adding a worker does not require any coordination beyond a common queue and a shared ceiling on requests per second.

A 401 halfway through the run stops everything 3. That usually means someone rotated the key, so the script alerts the owner instead of retrying a call that cannot succeed 3.

In the morning, a call to the free usage endpoint shows what the run spent, so finance can reconcile the job without a separate export 3. The same client code also serves an AI agent runtime that wraps REST calls as tools, or the fallback path next to an MCP server. The data still comes from the same B2B data provider, and only the caller changes.

REST API vs Model Context Protocol (MCP)

Both expose the same kind of capability to a caller. A REST API is called by code that a developer wrote. MCP exposes tools that an AI model chooses to call through a client 3.