What is a REST API?

Almost every app you use talks to a server through an API. The weather app asks for a forecast, a bot dashboard lists servers, a shop's website creates an order. In most cases that conversation follows the REST style.

REST is not a protocol or a library. It is a set of design rules, described by Roy Fielding in his 2000 doctoral dissertation and now applied on top of HTTP. Knowing those rules helps you both consume APIs and design your own.

How does a REST API work?#

The client (an app, a browser, a bot) sends an HTTP request to a URL. The server processes it and returns a response with a status code and, usually, a JSON body.

curl -i https://api.example.com/books/1

HTTP/1.1 200 OK
Content-Type: application/json

{"id": 1, "title": "Dom Casmurro"}

Three parts of the request matter: the method (what to do), the URL (on which resource) and, sometimes, a body with data. The response returns the status (whether it worked) and the representation of the resource, usually JSON.

What are the principles of REST?#

Fielding describes REST as a set of architectural constraints:

• Client and server are separate: the user interface and the data storage evolve independently.
• Stateless: each request carries everything the server needs, such as the auth token. The server keeps no session between calls.
• Cache: the response says whether it can be reused, which cuts traffic.
• Uniform interface: resources identified by URL and handled through representations, with self-descriptive messages and links between resources (hypermedia).
• Layered system: proxies, CDNs and load balancers can sit between client and server without the client noticing.
• Code on demand (optional): the server may send executable code to the client.

In practice, most "REST" APIs implement the first ideas well and skip hypermedia. That works, and it is what you will see every day.

Which HTTP method should you use for each action?#

Methods are defined in RFC 9110. Two concepts help you choose: a method is safe when it changes nothing on the server, and idempotent when repeating the call has the same effect as calling it once.

Idempotency matters when the network fails. If a DELETE /books/1 times out, you can retry safely. Retrying a POST may create two records.

How do you design URLs and status codes?#

URLs name things, not actions. The method already states the action.

• Good: GET /books, GET /books/1, POST /books, DELETE /books/1.
• Bad: GET /getBook?id=1, POST /deleteBook.

Use plurals for collections and nest only when the relationship is clear, like /authors/3/books. The most common status codes:

Returning 200 with {"error": true} in the body is a common mistake: it breaks clients, caches and monitoring tools that look only at the status.

What does a REST API look like in Node.js?#

With a recent Node.js version, install Express 5 and create server.mjs:

npm install express@5

import express from "express";

const app = express();
app.use(express.json());

const books = [{ id: 1, title: "Dom Casmurro" }];
let nextId = 2;

app.get("/books", (_req, res) => res.json(books));

app.get("/books/:id", (req, res) => {
  const book = books.find((b) => b.id === Number(req.params.id));
  if (!book) return res.status(404).json({ error: "Book not found" });
  res.json(book);
});

app.post("/books", (req, res) => {
  const { title } = req.body ?? {};
  if (typeof title !== "string" || title === "") {
    return res.status(400).json({ error: "title is required" });
  }
  const book = { id: nextId++, title };
  books.push(book);
  res.status(201).location(`/books/${book.id}`).json(book);
});

app.delete("/books/:id", (req, res) => {
  const i = books.findIndex((b) => b.id === Number(req.params.id));
  if (i === -1) return res.status(404).json({ error: "Book not found" });
  books.splice(i, 1);
  res.sendStatus(204);
});

app.listen(process.env.PORT ?? 3000);

Run it with node server.mjs and test:

curl -i localhost:3000/books/1
curl -i -X POST localhost:3000/books -H "Content-Type: application/json" -d '{"title":"Quincas Borba"}'
curl -i -X DELETE localhost:3000/books/2
curl -i localhost:3000/books/99

You should see 200, 201, 204 and 404. Data lives in memory and disappears on restart; a real API needs a database. Before publishing, go through the API production checklist.

When is a REST API not the best choice?#

REST works well for request and response operations on resources. It struggles elsewhere:

• Real time: chat, games and live prices need an open connection. See what a WebSocket is.
• Screens that need data from many resources: chaining many calls makes the screen slow, and GraphQL lets you ask for everything at once.
• Actions that are not CRUD: "approve order" does not always fit a resource. A POST /orders/5/approval usually does the job.

There is no universal winner. REST is the most common choice because it is simple, uses what HTTP already offers and any language can consume it.

How do REST, RESTful and related terms differ?#

• RESTful: an API that follows the REST style.
• HTTP API: a more neutral term, used when the API runs over HTTP but does not follow every constraint.
• RPC: remote function calls, like POST /createOrder. Actions instead of resources.
• Webhook: the reverse direction, where the server calls a URL of yours when something happens.

To put yours online, see how to host an API.

How to do this on Square Cloud#

A REST API is an application that listens on a port and answers HTTP requests, so the example above runs like any Node.js app. You deploy by uploading a ZIP in the dashboard, with the CLI, through GitHub or with the VS Code extension, and every web application gets a *.squareweb.app subdomain with HTTPS.

The squarecloud.app configuration file is optional: the dashboard generates it on deploy, with runtime, memory and main file. A web application needs at least 512 MB from your plan's RAM. There are runtimes for Node.js, Python, Go, Java, PHP and more. Every plan includes traffic with no bandwidth or per-request charges (fair use policy), DDoS protection and a WAF. If your API needs a database, hosting for PostgreSQL, MySQL, MongoDB and Redis starts on the Standard plan.

Square Cloud itself has a REST API (api.squarecloud.app/v2), with official SDKs in JavaScript/TypeScript, Python and Go. To publish yours, see the API hosting page.