What Is a REST API? Plain-English Definition, How It Works and a Worked Example in 2026

Your integration worked all last week. This morning a shipment lookup started returning 401, nothing in your code changed, and the vendor's status page is green. That gap, between code that looks right and an API that disagrees, is where most people meet REST properly. The fix is rarely clever: it is knowing what your request actually contained and what the response was trying to tell you.

How Does a REST API Work, Step by Step

A REST API publishes a list of URLs, where one URL identifies one kind of thing. /v1/shipments is the collection; /v1/shipments/4821 is one specific shipment. The verb you pair with that URL decides what happens to it.

Take a two person engineering team at a Pune logistics startup, wiring their ops dashboard to a courier partner's API. They have a base URL, a key and a page of docs. Here is what one lookup actually does.

The 5 HTTP methods you will actually use

Two columns matter more than people expect. Safe means the call changes nothing; idempotent means sending it five times leaves the server exactly as sending it once would. That second property is what makes a retry safe.

The Pune team's first bug is in that table. They retried failed POST calls on timeout and created duplicate shipments, because POST is not idempotent and a timeout never tells you whether the server finished. The fix is an idempotency key: a unique string per logical operation, sent as a header, so the server replays the original result instead of writing a second record. Most payment and logistics APIs document it under that exact name.

What Is a REST API? The 6 Constraints Behind the Name

REST stands for Representational State Transfer, described by Roy Fielding in his 2000 doctoral dissertation. He did not invent a product; he wrote down the properties that made the web scale, as constraints a system either satisfies or does not. Five are required and one is optional, which is why you see both "five" and "six" quoted.

1. Client and server are separate. They share only the interface, so either side can be rewritten alone.
2. Statelessness. Every request carries everything needed to serve it, which is exactly why you send your token on every call rather than logging in once.
3. Cacheability. Responses declare whether they may be stored and reused, via Cache-Control and ETag.
4. A uniform interface. Resources have identifiers, standard methods act on them, and responses name their own media type, such as application/json.
5. A layered system. The client cannot tell an origin server from a cache, a load balancer or a gateway. Also read: what load balancing actually does.
6. Code on demand, optional. The server may ship executable code to the client. Almost nobody does this deliberately.

Here is the honest part. Most APIs calling themselves RESTful break at least one constraint, usually the uniform interface, because they never return links telling the client what it can do next. In practice "REST API" now means "an HTTP API organised around resources that returns JSON", and that is what job ads mean too. Learn the constraints to understand why statelessness forces a token onto every call, then expect real APIs to honour only some of them.

A Worked REST API Example You Can Run in 60 Seconds

Reading about HTTP teaches you little; running two commands teaches you a lot. Open-Meteo needs no key at all, which makes it the cleanest first target available. Its terms page allows fewer than 10,000 API calls a day, 5,000 an hour and 600 a minute on the free non-commercial service, so practice will not come near the ceiling. One caveat from Open-Meteo's own blog: calls are weighted, so a request spanning over 14 days or over 10 weather variables counts as more than one.

Paste this into a terminal. The second pipes through jq so you see the JSON's shape instead of one long line.

curl -s "https://api.open-meteo.com/v1/forecast?latitude=18.52&longitude=73.86&current=temperature_2m"

curl -s "https://api.open-meteo.com/v1/forecast?latitude=18.52&longitude=73.86&daily=temperature_2m_max&timezone=Asia%2FKolkata" \
  | jq '.daily.time, .daily.temperature_2m_max'

Three things there generalise to every REST API you will call. The path /v1/forecast names a resource and carries a version. Everything after the question mark is a query parameter, shaping the response without changing which resource you asked for. The body is JSON with predictable keys, which is what makes it readable by code.

Now add -i to see headers, where the operationally useful information lives. GitHub's documentation puts unauthenticated requests at 60 an hour, a budget you can exhaust by accident.

curl -i -s -H "Accept: application/vnd.github+json" \
     -H "X-GitHub-Api-Version: 2026-03-10" \
     https://api.github.com/repos/python/cpython | head -20

# look for these in the output:
#   HTTP/2 200
#   x-ratelimit-limit: 60
#   x-ratelimit-remaining: 57
#   x-ratelimit-reset: 1762000000

If you do nothing else from this article, run those commands. Watching x-ratelimit-remaining fall by one per call is the moment the abstraction turns concrete.

Writing the other side: a REST API in 20 lines

Consuming an API is half the skill. Here is the smallest useful server, using FastAPI, whose release notes list 0.140.1 of 27 July 2026 as the latest published version at the time of checking. Prefer it over bare Flask for one reason: it builds an interactive OpenAPI page at /docs from your type hints, so the API documents itself.

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()
SHIPMENTS = {4821: {"id": 4821, "status": "in_transit", "city": "Pune"}}

class ShipmentIn(BaseModel):
    status: str
    city: str

@app.get("/v1/shipments/{shipment_id}")
def get_shipment(shipment_id: int):
    if shipment_id not in SHIPMENTS:
        raise HTTPException(status_code=404, detail="shipment not found")
    return SHIPMENTS[shipment_id]

@app.post("/v1/shipments", status_code=201)
def create_shipment(payload: ShipmentIn):
    new_id = max(SHIPMENTS) + 1
    SHIPMENTS[new_id] = {"id": new_id, **payload.model_dump()}
    return SHIPMENTS[new_id]

Run it with uvicorn main:app --reload and open http://127.0.0.1:8000/docs. Notice what declaring shipment_id: int bought you: send /v1/shipments/abc and the framework returns 422 naming the bad field, before your function ever runs. Validation at the edge is the highest value habit in API work. Endpoints like this are the plumbing under every deployed model, which is why they sit early in 360DT's AI Engineer course instead of being assumed knowledge.

REST API vs GraphQL: Which One Should You Learn First

GraphQL is the neighbour people confuse REST with, and the comparison teaches more than the definition does. GraphQL exposes one endpoint, usually POST /graphql, and the client's query names precisely which fields come back. REST exposes many endpoints, and the server decides what each returns.

The difference shows up most clearly in how GitHub, which runs both, has to meter them. For REST its docs set an authenticated personal access token at 5,000 requests an hour, where most GET, HEAD and OPTIONS calls cost 1 point and most POST, PATCH, PUT and DELETE calls cost 5. For GraphQL the same docs set 5,000 points an hour, then state plainly that 5,000 points is not 5,000 calls, because a query's cost comes from the first and last arguments on its connections. One GraphQL call can cost what dozens of REST calls would.

Learn REST first, and it is not close. Cloud control planes, webhooks, Indian payment gateways and nearly every tool an AI agent calls are REST shaped. GraphQL earns its weekend once you have a real over-fetching problem, and the trade-off you accept is giving up free HTTP caching and one-status-code-per-request error handling in exchange for precise reads. Good deal for a mobile screen, bad deal for a server to server integration a CDN could have cached. Choices of this shape are what AZ-305 objectives test, which is why a live Azure architect and DevOps program teaches them as trade-offs rather than syntax.

How GitHub Versions Its REST API, and Why Integrations Break

No tutorial covers this and every working engineer has been burned by it. An API is a promise, and the provider needs a way to change the promise without breaking you. GitHub's answer is the clearest published example.

GitHub names each version after its release date and asks you to send it in a header, for example X-GitHub-Api-Version: 2026-03-10. Its docs list two supported versions: 2026-03-10, with no end of support date scheduled, and 2022-11-28, whose support ends on 10 March 2028. Omit the header and your request silently defaults to the older 2022-11-28 behaviour. Send a retired version and you get 410 Gone. Each version is supported for 24 months after a newer one ships.

That default is the lesson. A client written three years ago that never set the header is still served 2022-11-28 today, and will keep working right until March 2028, then stop. So pin the version in your HTTP client, put the end of support date in a comment beside it, and set a reminder six months out. Twenty seconds of work separates a planned migration from a Monday morning outage.

Reading codes correctly is most of debugging, so keep this where you can find it at 2am.

Where You Will Meet REST APIs in Real Work

Giving a model tools. When an agent books a slot or checks stock, it is calling a REST endpoint: the model emits a structured call, your code turns it into an HTTP request, the JSON goes back into context. Every reliability problem in agent work is an API problem first, which means timeouts, retries, pagination and idempotency. Also read: how function calling works end to end. That is the daily substance of the AI Engineer program and of the CCDV-F developer prep course.

Moving data on a schedule. The Pune dashboard is the easy half. The hard half is a nightly job that pages through /v1/shipments?limit=100&cursor=..., takes a 429 halfway through page 40, and resumes without double counting. Orchestration against REST sources is ordinary data engineering, and a Microsoft Fabric data engineering course spends lab time on exactly it. From the reporting end, a Power BI and SQL analyst track teaches the same thing, since a web connector is a GET with a token.

Standing up and securing endpoints. Someone has to put the API behind a gateway, give it a certificate, rate limit it, log it and release it without downtime. That is cloud and DevOps ground, which a live AWS architect and DevOps course covers against the SAA-C03 and DOP-C02 objectives. If you integrate these systems inside a client's environment rather than owning them, that is closer to the Forward Deployed Engineer path. Also read: how microservices split one API into many.

What Is a REST API Bad At? Three Cases Where It Is the Wrong Tool

Knowing where REST stops is what separates someone who read a tutorial from someone who has shipped.

Streams. Live vehicle positions or a chat feed should not be a poll every two seconds. You burn quota, drain batteries and are still two seconds stale. Use WebSockets or server sent events, and keep REST for the first page load.

Deep nested reads. A screen needing a customer, their last five orders and each order's items is three or four round trips. That is the pain GraphQL was built for, and ignoring it produces sprawling one-screen endpoints that break when the screen changes.

Bulk data. Paging a hundred million rows through JSON is slow and expensive on both sides. If the provider offers a bulk export, a signed file URL or a replica, take it. Being the default does not make REST universal.

How to Learn REST APIs Properly

Six focused weekends takes you from reading docs to shipping an endpoint other people call. The sequence matters more than the hours, because each step leaves an artefact.

Skip two things people insist on: you do not need to read the HTTP specification end to end, and you do not need a GUI client, because curl hides nothing. For the guided version of weeks 3 to 6 with live review, that is what the AI Engineer course is built around, and the full certification tracks page shows how it sits beside the cloud and data routes.

What I Would Do in Your Position

Spend your first evening on curl and nothing else. Not Postman, not a framework, not a video: two commands against Open-Meteo, then the same call against GitHub with -i so you see the rate limit headers move. That hour fixes the mental model everything else rests on, and most people skip it because typing a URL feels too basic to count as learning. Then build the small FastAPI service above and deploy it, keeping the scope embarrassingly small: four endpoints, one table, real validation, real pagination. An endpoint a stranger can call beats three certificates with no artefact behind them.

After that it stops being a question about REST and becomes a question about what you point it at. If the answer is agents and model APIs, the AI Engineer course is the direct route, and a free webinar costs nothing if you want to watch a live session first. Prefer to test it against your own background? Book a demo class and bring your week 3 code.

Related guides

• What is CI/CD, how the pipeline works read this when your API is written and you need it deployed on every merge rather than by hand.
• Containerise a Python API in 7 steps the literal next action after week 5 of the plan above.
• How OAuth 2.0 works where the bearer token in your headers actually comes from, and how servers validate it.
• Solutions architect or DevOps engineer the two roles that own API design and API operations once you are past junior work.
• AI engineer pay in India what the integration and agent skills in this guide are currently advertised at.

Frequently asked questions

About this guide. 360 Digital Transformation is an Anthropic Partner and a Microsoft Authorized Training Partner. Other certification bodies, vendors and employers named here are not affiliated with us. Tools and versions change quickly; commands and figures cited were checked on 31 October 2026.