Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 39 ยท HTTP and REST Fundamentals

What Is a REST API?

Learn what an API is, what makes an HTTP API RESTful, the six REST constraints, the Richardson maturity model and how REST compares with RPC and GraphQL.

An API (application programming interface) is a contract that lets one program talk to another without knowing how the other one works inside. A weather app on your phone does not read a meteorologist's database. It asks a server for the forecast, and the server answers in a format both sides agreed on. The agreement, meaning which requests are allowed and what the answers look like, is the API.

A web API carries that conversation over HTTP, the same protocol your browser uses to load pages. A REST API is a web API that follows a particular architectural style. In this lesson you learn what that style asks for, why it became the default for public and internal APIs, and what it looks like in a working program.

Clients, servers and resources

Every web API has two roles. The client (a mobile app, a web page, a script, another server) sends a request. The server owns the data, decides what the client may do and sends a response.

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: GET /books/42
    S-->>C: 200 OK + JSON representation of book 42
    C->>S: PUT /books/42 (new representation)
    S-->>C: 200 OK
    C->>S: DELETE /books/42
    S-->>C: 204 No Content

A client talks to a server by exchanging representations of resources.

REST stands for Representational State Transfer. The name comes from Roy Fielding's 2000 doctoral dissertation, which described the architecture that made the early web scale. Three words carry most of the idea:

  • Resource: anything the API can name, such as a book, a user, an order or a collection of orders. Each resource has an address (a URL).
  • Representation: a snapshot of the resource's state in some format, usually JSON. The client never touches the database row; it receives and sends representations.
  • Transfer: the client changes state by sending a representation (or a method such as DELETE) back to the server.

So https://api.example.com/books/42 is not "a function that returns a book". It is the name of book 42. What you do with it depends on the HTTP method: GET reads it, PUT replaces it, DELETE removes it.

The six REST constraints

Fielding described REST as a set of constraints. An API that obeys all of them is called RESTful. Most real-world APIs obey most of them.

Six REST constraints

Client-server UI and data storage are separate concerns.
Stateless Every request carries all it needs.
Cacheable Responses say if they may be reused.
1 / 2

Stateless is the one that shapes day-to-day design the most. The server does not remember the client between requests. If a call needs to know who you are, the request itself must say so (a token in a header, for example). Statelessness is what lets you put ten identical servers behind a load balancer: any of them can answer any request.

Uniform interface means the same small vocabulary everywhere: identify things by URL, act on them through the standard HTTP methods, describe the payload with a media type such as application/json, and (in its strictest form) let responses contain links to what you can do next. You will see how this plays out in HTTP methods and resource naming.

Cacheable responses let browsers, CDNs and proxies answer repeated reads without bothering your server. See headers and content negotiation.

The Richardson maturity model

Leonard Richardson proposed four levels to describe how "REST" an HTTP API is:

Level Name What it looks like
0 The swamp of POX One URL, everything is POST /api with an action in the body
1 Resources Many URLs, one per resource, but still mostly POST
2 HTTP verbs Proper methods (GET, POST, PUT, DELETE) and status codes
3 Hypermedia controls Responses include links that tell the client what to do next

Most successful APIs you will meet sit at level 2: resources, verbs and status codes. Level 3 (often called HATEOAS) is valuable for discoverable, long-lived APIs, but few teams implement it fully. This course teaches level 2 thoroughly and shows where links help.

REST, RPC and GraphQL

REST is not the only style:

  • RPC (remote procedure call) exposes actions: POST /createUser, GET /getUserById?id=7. It maps naturally to code ("call this function on the server") and can be simple and fast. gRPC is a modern, binary version.
  • GraphQL exposes one endpoint and lets the client describe exactly the fields it wants. It shines when many different clients need different shapes of the same data.
  • REST exposes nouns and uses the HTTP methods as the verbs. It works with everything the web already has: caching, status codes, proxies and browsers.

None of them is "the best". REST is a strong default for CRUD-heavy resource APIs, public APIs and anything that benefits from HTTP caching.

See it run

The Node.js runner below starts a real HTTP server on a random local port and calls it with fetch, so you can see an API request and response end to end. The same server offers an RPC-style endpoint and a REST-style endpoint for the same book.

Node.js One book, two API styles

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice how the REST version reuses the same URL for reading and deleting. The method changes the meaning, and the status codes (200, 204, 404) tell the client what happened without parsing a message.

What a RESTful design gives you

When an API follows these rules, a developer who has never seen it can guess most of it. If GET /books lists books and GET /books/42 returns one, then GET /authors and GET /authors/7 almost certainly exist. Tools (HTTP clients, API gateways, caches, test frameworks, documentation generators) understand the conventions too. That predictability is the real reason REST won.

Node.js Guess the API: representations are just data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the "representational" in REST refer to?

    A resource is exchanged as a representation (a format such as JSON). The client never accesses the underlying storage.
  2. 2. Why does the stateless constraint help scaling?

    Without per-client memory on the server, you can add or remove identical instances behind a load balancer freely.
  3. 3. Which request is the most RESTful way to delete book 42?

    The URL names the resource and the HTTP method DELETE names the action.
  4. 4. At which Richardson level do most production APIs sit?

    Level 2 is the common practical target. Level 3 (hypermedia controls) is rarer.

Summary

  • An API is a contract between programs; a web API carries it over HTTP.
  • REST is an architectural style: resources named by URLs, exchanged as representations, manipulated with standard methods.
  • The constraints are client-server, stateless, cacheable, uniform interface, layered system and optional code on demand.
  • The Richardson model grades APIs from one-URL RPC (level 0) up to hypermedia (level 3); level 2 is the usual goal.
  • REST, RPC and GraphQL solve different problems; REST is a strong default for resource-oriented APIs.

Next: HTTP Requests and Responses