RESTful API example: one request, one response, explained

What a RESTful API looks like

A RESTful API exposes resources at URLs and lets a client act on them with HTTP methods. The resource is a noun (a search, a record, a monitor); the method is the verb (POST creates, GET reads, DELETE removes); the body and the response are JSON. That is the whole idea. Everything else — authentication, versioning, errors, pagination — is convention layered on top, and the conventions are what this page shows with a working example.

The API used throughout is the OffenderSearch background check API: one request searches 58 US sex offender registries (or, on a sibling endpoint, criminal records) and returns the matching people as JSON. It is a good teaching API because the response is rich enough to be interesting and the sandbox is free, so every example here is one you can run.

API endpoint example: the URL, piece by piece

An API endpoint is a method plus a URL. The endpoint example this page uses is POST https://sandbox.offendersearch.app/v1/search. Read it from left to right:

There is no query string on a search because the query is a JSON body. Endpoints that read a resource put the id in the path (/v1/searches/srch_…), never in a query parameter — that keeps URLs cacheable and ids out of referrer headers. The full endpoint list is on the API reference.

API request example in cURL, Python and Node

Three identical requests. The header X-API-Key authenticates (see API token example for how to get one); Content-Type: application/json tells the server how to read the body. The test name Exact Match with date of birth 1980-01-01 is a fixed sandbox person, so the response is the same every time — a real request, a deterministic answer.

curl -X POST https://sandbox.offendersearch.app/v1/search \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": {"firstName": "Exact", "lastName": "Match", "dob": "1980-01-01"}}'

The API request body: a JSON schema you can read

The request body is one JSON object with a query object inside it. Wrapping the query in a named object is deliberate: the same envelope later carries optional blocks (live, proof, include) without changing the shape of what you already send.

Validation is strict and the error names the field (see the error shape below). The exact JSON schema is published in the OpenAPI document, which is also what the Postman collection and the SDKs are generated from.

API response example: the JSON, field by field

This is the response to the request above, as the sandbox returns it (the sandbox adds "sandbox": true; production omits it). It is a response envelope: metadata about the search first, the matching records last.

{
  "searchId": "srch_7c1e9a2b4f5d6e8091a2",
  "status": "complete",
  "elapsedMs": 118,
  "sandbox": true,
  "counts": { "records": 1, "recordsReturned": 1, "sourcesQueried": 58, "sourcesComplete": 58, "sourcesIncomplete": 0 },
  "warnings": [],
  "sourceStatus": [
    { "source": "OH", "status": "ok", "matched": 1, "fromCache": true, "incomplete": false, "incompleteReason": null }
  ],
  "records": [
    {
      "recordId": "rec_0a1b2c3d4e5f60718293",
      "matchConfidence": 0.96,
      "matchBasis": ["lastName:exact", "firstName:exact", "dob"],
      "matchState": "dob_match",
      "name": { "first": "Exact", "middle": "Sample", "last": "Match", "suffix": "", "full": "Exact Sample Match" },
      "dob": "1980-01-01",
      "dobPrecision": "exact",
      "registrationState": "OH",
      "addresses": [
        { "type": "residence", "line1": "100 Sample St", "city": "Sampleville", "county": "Sample", "state": "OH", "zipcode": "00000" },
        { "type": "employment", "line1": "200 Example Ave", "city": "Sampleville", "county": "Sample", "state": "OH", "zipcode": "00000" }
      ],
      "offenses": [
        { "crime": "Sexual battery", "statute": "SAMPLE 2907.03", "tier": "Tier III", "convictionDate": "2004-05-12", "registrationDate": "2008-02-01" }
      ],
      "sources": [
        { "jurisdiction": "OH", "registryName": "Ohio eSORN", "recordUrl": "https://…", "lastCheckedAt": "2026-10-27T03:10:00+00:00" }
      ]
    }
  ]
}

GET, POST and DELETE: the same resource, three verbs

A RESTful API reuses the same URL shapes for every verb. The POST above created a search; a GET on /v1/searches/{searchId} reads it back without re-running it (and without a second charge on the live host); a DELETE on a monitor stops it. Note what changes and what does not: the host, the header and the version prefix are identical, only the method and the path differ.

# A GET: read a search you already created (no body, the id is in the path)
curl https://sandbox.offendersearch.app/v1/searches/srch_7c1e9a2b4f5d6e8091a2 \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY"

# A DELETE: stop a monitor (an empty body answers 204)
curl -X DELETE https://sandbox.offendersearch.app/v1/monitors/mon_4d5e6f70819a2b3c4d5e \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY"

Because POST is not idempotent, a client that retries a dropped POST must first check whether the first one succeeded. The API gives you the tool for that: persist the searchId as soon as any acknowledgement arrives, then recover by GET. The async jobs guide walks through it; webhooks vs API polling covers when to be told instead of asking.

API errors and status codes in a RESTful API

REST uses the HTTP status code as the first word of every error and a JSON body as the sentence. Here is the body you get when the request above forgets lastName:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "detail": [
    { "loc": ["body", "query", "lastName"], "msg": "field required", "type": "value_error.missing" }
  ]
}

Branch on the status and on detail.code, never on the English sentence, which can be reworded. The full catalogue, including the criminal-records error object, is in API errors and the errors reference.

Create a RESTful API client in 30 lines

A RESTful API client is a thin object that owns three things: the base URL, the headers, and the rule for errors. Everything else is one method per endpoint. Here is a complete one in Python and in JavaScript, with the one piece of resilience every client needs — honouring Retry-After on a 429.

import os, time, requests

class OffenderSearch:
    """A minimal RESTful API client: one base URL, one header, one error type, retries on 429."""

    def __init__(self, key: str, base: str = "https://sandbox.offendersearch.app"):
        self.base, self.s = base, requests.Session()
        self.s.headers.update({"X-API-Key": key, "Content-Type": "application/json"})

    def _call(self, method: str, path: str, **kw):
        for attempt in range(4):
            r = self.s.request(method, f"{self.base}{path}", timeout=60, **kw)
            if r.status_code == 429:                        # rate limited: wait what the server says
                time.sleep(int(r.headers.get("Retry-After", "5")))
                continue
            if r.status_code >= 400:
                raise RuntimeError(f"{method} {path} -> {r.status_code}: {r.text}")
            return r.json() if r.content else None
        raise RuntimeError("gave up after four 429s")

    def search(self, first: str, last: str, dob: str | None = None, state: str | None = None):
        q = {"firstName": first, "lastName": last}
        if dob: q["dob"] = dob
        if state: q["state"] = state
        return self._call("POST", "/v1/search", json={"query": q})

    def get_search(self, search_id: str):
        return self._call("GET", f"/v1/searches/{search_id}")

client = OffenderSearch(os.environ["OFFENDERSEARCH_TEST_KEY"])
print(client.search("Exact", "Match", dob="1980-01-01")["counts"]["records"])   # 1

If you would rather not maintain this, the official packages do the same with typed responses: pip install offendersearch and npm i @offendersearch/sdk — see SDKs. Both are generated from the same OpenAPI document the docs are built from, so they cannot drift from what the server does.

RESTful API design conventions this example follows

• Versioned paths (/v1), so breaking changes are a new prefix, not a surprise.
• JSON in, JSON out, with Content-Type: application/json on every request that has a body.
• Ids are opaque strings with a prefix (srch_, rec_, mon_), so a log line tells you what kind of thing an id is without a lookup.
• Sensitive input travels in the body, never in the URL.
• One error shape: a status code plus a JSON detail you can branch on.
• `Retry-After` on every `429`, so a client never has to guess a backoff.
• Async is explicit: when work takes longer than a request, the API answers 202 with an id and a path to poll, rather than holding the connection open. Covered in webhooks vs API polling.
• A sandbox with the production shape, so the test you wrote is the integration you ship — see public API for testing.

These are the same conventions you will meet on any well-run REST API. Learning them on one API with a free sandbox is faster than reading them in the abstract; the what is an API glossary defines each term.

A second RESTful API example: criminal records on a sibling endpoint

Consistency is the payoff of REST. The criminal records API lives at POST /v1/criminal/search with the same header, the same query object and the same envelope idea; only the record shape differs (court cases, jail bookings, warrants, custody). The sandbox person Felony Record, born 1975-06-15, returns one court case:

curl -X POST https://sandbox.offendersearch.app/v1/criminal/search \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": {"firstName": "Felony", "lastName": "Record", "dob": "1975-06-15"}}'

The record comes back as recordType: "court_case" with severity: "felony", disposition: "Guilty" and matchState: "dob_match". Swap the name for Arrest Only (born 1992-04-20) and you get a jail_booking with no disposition — a booking is not a conviction, and the API says so in the data rather than in prose. Every fixed criminal test name is listed on the criminal sandbox page.

What this example does not cover

• OAuth and user login. This API authenticates a server with an API key; there is no end-user authorization flow. If you need to know when OAuth is the right tool instead, read API key vs OAuth.
• GraphQL or gRPC. Different styles with different trade-offs; the REST conventions here do not transfer one to one.
• Pagination of huge collections. A search returns the matches for one person; the long-list cases (alerts, FCRA events) use cursor paging documented on their own pages.
• Bulk uploads. A CSV of thousands of names goes through the batch endpoint, which is asynchronous by design.
• What the data does not include. The API returns sex offender registry and criminal public records. It does not run credit checks, driving records, identity verification or international searches, and it never asks for a Social Security number.

FAQ: restful api example questions, answered

What is an example of a RESTful API?

Any HTTP API that exposes resources at URLs and uses the HTTP methods for actions: POST /v1/search to create a search, GET /v1/searches/{id} to read it, DELETE /v1/monitors/{id} to remove a monitor. The request and response above are a complete, runnable example.

What does a REST API request look like?

A method, a URL, headers (X-API-Key, Content-Type: application/json) and, for POST, a JSON body. The cURL tab in the request example is the literal bytes on the wire.

What is an API endpoint URL example?

https://sandbox.offendersearch.app/v1/search — scheme, host, version prefix, resource path. The method (POST) is part of the endpoint even though it is not part of the URL.

What is a JSON API?

An API whose request bodies and responses are JSON documents, declared with Content-Type: application/json. Nearly every REST API today is a JSON API; the term also names a specific specification (jsonapi.org) that this API does not use.

How do I test a REST API example without paying?

Use a sandbox. Here, a free account gives you test keys that work on sandbox.offendersearch.app with fixed test names and the production response shape, never billed. The live host also includes 25 free calls on sign-up with no card. Details on public API for testing.

How do I create a RESTful API client?

Wrap the base URL, headers and error rule in one object and add a method per endpoint, as in the 30-line client. Or install the generated SDK and skip it.

Related

• Learn APIs by example (hub) — every guide in this series
• What is an API? Glossary — every term used above, defined
• API token example — getting and handling the key
• API errors — the full error catalogue
• Webhooks vs API polling — when to be told instead of asking
• Public API for testing — the free sandbox this page runs on
• Background check API — the product behind the example
• Sex offender API — 58 US registries in one call
• Criminal records API — the sibling endpoint
• Quickstart — the product quickstart
• Authentication — keys, hosts and security
• Top 5 background check APIs compared — how this API compares