CodingNic
Sign In Book Session

Web APIs and Backend Communication

REST APIs and Conventions

Web APIs and Backend Communication 20 min read

REST APIs and Conventions

Objectives

By the end of this chapter, you should be able to:

  • Explain what REST means in practical terms
  • Read a REST URL and predict what it returns
  • Recognize the major HTTP status code families and what each means

💡 Why this matters: Module 3 taught fetch() itself. This lesson teaches the conventions almost every real API follows, so a new API you’ve never seen still feels familiar, instead of like reading unfamiliar documentation from scratch every time.

⚠️ A note on verification: this module continues using JSONPlaceholder, the same practice API from Module 3. This sandbox’s network access is still restricted to a small allowlist that doesn’t include it, so fetch() calls against it can’t run live here, the same limitation as Module 3. The URLs, data, and status codes below are real, pulled directly from the live API.

What “REST” Actually Means

REST (Representational State Transfer) isn’t a specific technology, it’s a set of conventions for designing an API around resources, things like users, posts, or products, each identified by its own URL. Almost every API you’ll work with professionally follows these conventions closely enough that learning them once pays off everywhere.

Resources Are Nouns, Methods Are Verbs

A REST URL identifies what you’re working with. The HTTP method (Module 3 briefly touched GET, next lesson covers the rest) says what to do with it.

text
GET /users        → get a list of users
GET /users/1      → get the user with id 1
POST /users       → create a new user
PUT /users/1      → replace the user with id 1
DELETE /users/1   → delete the user with id 1

Notice the URL for “get one user” and “delete that user” is identical, /users/1, the method is what changes the meaning. This is the core REST idea: URLs name resources, methods describe the action.

Resource Names Are Plural Nouns

/users, not /user, /getUser, or /user-list. This is a convention, not a hard rule enforced by HTTP itself, but it’s followed so consistently that breaking it looks like a mistake. JSONPlaceholder follows it throughout: /users, /posts, /todos, /comments, /albums, /photos, all plural, all nouns, never a verb in the URL itself.

javascript
const response = await fetch("https://jsonplaceholder.typicode.com/posts/1");
const post = await response.json();
console.log(post);
// { userId: 1, id: 1, title: "sunt aut facere...", body: "quia et suscipit..." }

The verb, “get,” is expressed by the HTTP method (a plain fetch() defaults to GET), not by anything in the URL.

Nesting Shows a Relationship

A URL can nest one resource inside another to express “the posts belonging to this user,” for example.

javascript
const response = await fetch("https://jsonplaceholder.typicode.com/users/1/posts");
const posts = await response.json();
console.log(posts.length);
// 10 (every post written by user 1)

/users/1/posts reads naturally: posts, belonging to user 1. Compare that to a flat, non-nested alternative like /posts?userId=1, both are common in real APIs (JSONPlaceholder actually supports the query-parameter version too), nesting communicates a relationship more directly, filtering with a query parameter is often more flexible. Neither is “more correct,” different APIs make different choices here.

Status Codes Tell You What Happened

Every response carries a status code (response.status, Module 3), and they fall into predictable families based on the first digit.

text
2xx  Success             200 OK, 201 Created, 204 No Content
4xx  Client error        400 Bad Request, 401 Unauthorized, 404 Not Found
5xx  Server error        500 Internal Server Error, 503 Service Unavailable

A 2xx means your request worked. A 4xx means something about your request was wrong, a bad ID, missing data, no permission. A 5xx means the request was fine, but the server itself failed to handle it. This distinction matters when deciding how to react: a 4xx usually means fix the request and don’t just retry it as-is, a 5xx might genuinely be worth retrying, the server could recover.

javascript
const response = await fetch("https://jsonplaceholder.typicode.com/users/1");
console.log(response.status);
// 200

const missing = await fetch("https://jsonplaceholder.typicode.com/users/9999");
console.log(missing.status);
// 404

response.ok (Module 3) is a shortcut for “status is in the 2xx range,” it’s false for both 4xx and 5xx, since neither means success, even though the specific problem is very different between them.

A Few Specific Codes Worth Recognizing

  • 200 OK: the standard success response for GET, PUT, PATCH.
  • 201 Created: success, specifically for a POST that created something new.
  • 204 No Content: success, but there’s nothing to send back, common for DELETE.
  • 400 Bad Request: the request itself was malformed, missing required data, invalid format.
  • 401 Unauthorized: the request needs authentication that wasn’t provided (next lesson but one).
  • 403 Forbidden: authentication was provided, but this user isn’t allowed to do this.
  • 404 Not Found: no resource exists at this URL.
  • 500 Internal Server Error: the server hit an unexpected problem handling an otherwise valid request.

Try It

  1. Given the URL pattern /products/:id, write what URL you’d request to get product 42, and what HTTP method you’d use.
  2. Given /products, write the URL and method to create a new product.
  3. Fetch https://jsonplaceholder.typicode.com/albums/1/photos and log how many photos come back. Explain, in your own words, what this nested URL represents.
  4. A request returns status 403. Explain, in your own words, how that’s different from a 401, and what each suggests about what went wrong.

Recap

  • REST URLs identify resources with plural nouns (/users, /posts), the HTTP method describes the action taken on them.
  • Nesting one resource inside another (/users/1/posts) expresses a relationship, a flat URL with a query parameter (/posts?userId=1) often expresses the same relationship differently.
  • Status codes fall into families by their first digit: 2xx success, 4xx a problem with the request, 5xx a problem on the server.
  • response.ok covers the entire 2xx family, checking the specific status code tells you more about exactly what happened.

Next lesson: the HTTP methods themselves, GET, POST, PUT, PATCH, and DELETE, and what each is actually for.