Module 1: API Foundations

What Makes an API RESTful

Almost every app you use talks to a server through an API. A mobile banking app asks for your balance, a delivery app asks where your rider is, and a shop website asks for the product list. An API (Application Programming Interface) is the agreed way one program asks another for data or for an action. REST is the most common style for web APIs, and understanding it properly will make every API you build easier to use, easier to change and easier to secure.

REST is an architectural style, not a library

REST stands for Representational State Transfer. It was described by Roy Fielding in his 2000 doctoral dissertation as a set of constraints for building systems that work well over the web. You do not install REST. You follow its rules using ordinary HTTP, the same protocol your browser uses to load web pages. An API is called RESTful when it respects those constraints in a sensible, consistent way.

The main constraints are:

• Client and server are separate. The client (a phone app, a website, another server) only knows the API. The server can change its database or language without breaking the client, as long as the API contract stays the same.
• Stateless requests. Every request carries everything the server needs to understand it, such as the authentication token and the data. The server does not remember "where the client was" between requests.
• Cacheable responses. Responses say whether they may be cached, so clients and proxies can reuse them and reduce load.
• A uniform interface. Resources are identified by URLs, and you act on them with a small, standard set of HTTP methods. This is the part you will use every day.
• A layered system. The client does not need to know whether it is talking to the real server, a load balancer or a cache.

Thinking in resources

The heart of REST is the resource: a thing your system manages, such as a customer, an order or an invoice. Each resource has an address (a URL), and the client receives a representation of it, usually JSON. Instead of designing an API as a list of functions ("getCustomerBalance", "makeNewOrder"), you design it as a set of nouns and let HTTP methods supply the verbs.

Compare these two designs for a small Nairobi hardware shop that wants an API for its orders:

The RESTful version is shorter, predictable and self-explaining. A developer who has seen /orders can guess how /customers works without reading the documentation.

A worked example: one request and response

Here is what a RESTful exchange looks like on the wire. The client asks for order 42:

GET /orders/42 HTTP/1.1
Host: api.example-shop.co.ke
Accept: application/json
Authorization: Bearer eyJhbGciOi...

The server replies with a status code, headers and a JSON representation:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: private, max-age=0

{
  "id": 42,
  "customerId": 7,
  "status": "paid",
  "totalKes": 4500,
  "items": [
    { "sku": "NAIL-50MM", "quantity": 3, "unitPriceKes": 1500 }
  ],
  "createdAt": "2026-03-02T09:15:00Z"
}

Notice the statelessness: the token travels with the request, so any server behind a load balancer can answer it. Notice the uniform interface: the method says "read", the URL says "which thing", and the status code says "it worked".

In Node.js with Express, the server side of this endpoint can be as short as:

app.get('/orders/:id', async (req, res) => {
  const order = await db.orders.findById(req.params.id);
  if (!order) return res.status(404).json({ error: 'Order not found' });
  res.json(order);
});

How strict do you need to be?

Fielding's full definition also includes "hypermedia as the engine of application state" (HATEOAS), where responses contain links telling the client what it can do next. Very few public APIs implement this fully. In practice, "RESTful" usually means resource-based URLs, correct HTTP methods, meaningful status codes, JSON bodies and stateless authentication. Aim for that solid, practical level first. You can add links such as "next" in paginated responses where they help.

Common mistakes to avoid

• Verbs in URLs. /createUser duplicates what the method already says. Use POST /users.
• Using GET to change data. GET requests can be cached, prefetched by browsers or repeated by crawlers. A GET that deletes something will eventually delete it by accident.
• Returning 200 for everything. If the order does not exist, say so with 404, not a 200 with "success": false.
• Server-side sessions that tie a client to one machine. They break statelessness and make scaling harder.
• Inconsistency. Mixing /orders, /Order and /get-customers in the same API confuses everyone. Consistency matters more than any single rule.

In the next lessons you will look closely at methods and status codes, then at designing clean URLs, so that you can apply these principles with confidence.