How a REST API works and how to call one

What it is

The way one program talks to another. Not a person in a browser but code: a mobile app to a server, a page to a server, one system to another.

The core idea of the approach: every entity has an address, and the action performed on it is expressed by the request method.

Methods

Five that matter in practice:

• GET — retrieve. Should change nothing.
• POST — create something new.
• PUT — replace entirely.
• PATCH — modify partially.
• DELETE — remove.

The difference between the two modification methods comes up at interviews often: the first replaces the object wholesale, the second changes only the fields you sent.

Addresses

The conventions are:

GET    /notes         list of notes
GET    /notes/42      one note
POST   /notes         create a note
PATCH  /notes/42      modify a note
DELETE /notes/42      delete a note

Plural nouns, with the action expressed by the method rather than the address. An address like "/getNotes" contradicts the approach, though it works technically.

Status codes

The first digit tells you what happened:

• 2xx — it worked. 200 success, 201 created, 204 success with no content.
• 3xx — redirection.
• 4xx — the caller's error. 400 bad request, 401 not identified, 403 identified but not permitted, 404 not found, 429 too frequent.
• 5xx — a server error. Your request wasn't the problem.

The difference between 401 and 403 is asked at almost every interview. The first is "who are you?", the second "I know who you are and you may not".

Reading someone's documentation

The order:

1. Find the base address — the common prefix for all calls.
2. Check whether a key is needed and how to send it: usually in a header.
3. Find the relevant section and note the method, address and required parameters.
4. Look at a sample response. More useful than field descriptions: the structure is immediately visible.
5. Check the rate limits.

Good documentation gives a ready request you can copy and run.

Calling it from code

async function loadNotes() {
  const res = await fetch("https://example.com/api/notes", {
    headers: { Authorization: "Bearer " + token },
  });

  if (!res.ok) {
    throw new Error("Server responded " + res.status);
  }

  return res.json();
}

The key detail: checking for success is mandatory. A request returning an error isn't treated as a failure by itself — you must inspect the status. A forgotten check leads to baffling parsing errors, because an error description arrived instead of data.

Common mistakes

A key in the code. Anything that reaches a public repository is exposed. Keys go in environment variables.

No error handling. The server may not answer, may answer with an error, may answer with the wrong thing. All three need covering.

A request on every render. A classic in interfaces: you forgot to specify when to call, and got an infinite loop of requests.

Ignoring rate limits. You'll get blocked and spend a long time working out why everything broke.

Sending data in the wrong shape. If the server expects an interchange format, you need both the matching header and the data converted.

How to practise

Take any open service with free access — weather, exchange rates, reference data — and build a page that fetches from it and displays the result, handling loading and errors.

That's the classic learning exercise, and it's also half of a front-end developer's job.