REST API Design | Learn IT Fundamentals with Teacher Pochi

Key points

A REST API is an API design style that separates "what" (the resource) from "what to do to it" (the operation).
The "what" is represented by the URL, and "what to do" is represented by the HTTP method (GET, POST, PUT, DELETE, etc.).
Designing along these lines produces an API whose meaning is easy for anyone to understand at a glance.

What is a REST API?

REST (Representational State Transfer) is one way of thinking about how to design an API on the web. At its core is the idea that "the thing you want to operate on (the resource) is represented by a URL, and what you want to do to it is represented by an HTTP method."

For example, an API for "getting a list of users" is expressed by combining "users, the resource" with "retrieve, the operation."

Resource-oriented URL design

The basic rule for REST API URLs is to design them around nouns (the target itself) rather than verbs (an action). That's because "what to do" is expressed on the HTTP method side, not in the URL.

https://api.example.comAPI server

/usersResource (plural noun)

/123Individual ID

Rather than a verb-laden URL like /getUser, the resource-oriented approach represents things as "target + ID," like /users/123.

Teacher Pochi's hintThink of the spine labels on a library bookshelf. The shelf doesn't say "please take me" — it just identifies the thing itself, like "novels section, No. 123." What you do with it (borrow it, return it) is determined by the visitor's action, not by the label on the shelf.

Expressing operations with HTTP methods

By using different HTTP methods against the same URL (resource), you can express different operations.

GET /users/123retrieve it

POST /userscreate a new one

PUT /users/123replace it entirely

DELETE /users/123delete it

By keeping the URL (the target) fixed and changing only the method, you can express the basic CRUD operations (create, retrieve, update, delete) simply and clearly.

How this relates to status codes

The outcome of an operation is communicated through the response's status code. In REST API design, it matters that the right status code is returned for the type of operation performed.

2xx rangeSuccess. Example: 201 for a successful creation, 200 for a successful retrieval.

4xx rangeA problem with the request. Example: 404 for an ID that doesn't exist.

5xx rangeA problem on the server side. Example: 500 if an error occurs while processing.

The detailed meaning of status codes themselves is covered in the HTTP topic under web fundamentals. Here, focus on the design role they play: "communicating the outcome of an operation clearly, through the type of code returned."

Principles of good API design

Represent the URL as a noun (the resource), and leave the verb (the operation) to the method.
Use a consistent naming convention for the same kind of target (e.g., always plural).
Communicate the outcome clearly through both the status code and the response content.

Following these rules makes it easier for anyone touching the API for the first time to predict "what will happen with this URL and this method."

Practical pitfalls to watch for

Designing without versioning in mindIf compatibility breaks with every spec change, existing consumers get affected. Building in version awareness — like a /v1/ segment in the URL — matters from the start.

Inconsistent error response formatsWhen each endpoint reports errors differently, the code calling your API gets more complex. Standardize your error codes and message format.

Decide authentication and authorization earlySettling on how access is controlled — API keys, OAuth, and who can do what — early in the design avoids costly rework later.

Summary

REST API design is a design style where the URL represents "what," and the HTTP method represents "what to do to it." Being deliberate about resource-oriented URLs and the choice of method lets you build APIs whose meaning is easy to understand.