Software Engineering Roadmap

Learn how to build, test, deploy, and maintain robust software systems.

Overall Progress0%

RESTful APIs

Explanation

An API (Application Programming Interface) is a contract that lets one piece of software talk to another. A RESTful API is an API designed around a set of architectural principles: resources identified by URLs, a small set of HTTP methods, and stateless communication. This lesson teaches how to design an API that is predictable, well-documented, and safe: resources and methods, status codes, validation, pagination, authentication and authorization, and API documentation with OpenAPI. Good API design is what makes an API pleasant to use for years. Bad API design is what makes clients hate you.

What Is an API?

Client

↓

API (contract)

↓

Server / application

The API is the interface: the documented ways a client can interact with a system.

What Is REST?

REST (Representational State Transfer) is an architectural style, not a single tool. Its core idea is that clients interact with resources through a small, uniform set of operations. It is more than "GET reads and POST creates."

Client-server: the UI and the server are separated.
Stateless: each request carries what it needs.
Cacheable: responses can be cached.
Uniform interface: resources are addressed consistently.
Layered system: the client does not need to know what is behind the API.

Resources and URLs

Design around resources (nouns), not actions. A resource is a thing: a user, a post, an order.

text

1/users      → the collection of users2/users/123  → one user3/posts      → the collection of posts4/posts/123  → one post

HTTP Methods

Method	Purpose	Idempotent?
GET	Read a resource	Yes
POST	Create a resource	No
PUT	Replace a resource	Yes
PATCH	Partially update a resource	No
DELETE	Remove a resource	Yes

Status Codes

Code	Meaning
200	OK
201	Created
204	No content
400	Bad request
401	Unauthorized
403	Forbidden
404	Not found
409	Conflict
422	Unprocessable entity
429	Too many requests
500	Internal server error
503	Service unavailable

Use the right code. 401 means "not authenticated"; 403 means "authenticated but not allowed"; 404 means "does not exist."

A CRUD Blog API

text

1GET    /posts        → list posts2GET    /posts/:id    → one post3POST   /posts        → create a post4PATCH  /posts/:id    → update a post5DELETE /posts/:id    → delete a post

Validation and Error Responses

Never trust client input. Validate required fields, types, lengths, and allowed values. Return a consistent error structure so clients can react predictably.

json

1{2  "statusCode": 400,3  "message": "title is required"4}

Pagination

Never return thousands of records at once. Paginate with an offset or a cursor.

	Offset pagination	Cursor pagination
How	page and limit	A cursor pointing at the next item
Pros	Simple	Stable under inserts/deletes
Cons	Drifts when data changes	Slightly more complex

Authentication vs Authorization

Authentication: "Who are you?"
Authorization: "What are you allowed to do?"

JWT and OAuth

A JWT (JSON Web Token) is a signed token issued at login and sent with each request to prove identity. OAuth is a standard for delegated authorization — letting an app act on a user’s behalf without knowing their password.

↓

Issue token

↓

Request with token

↓

Verify token

↓

Authorized resource

OpenAPI and Documentation

OpenAPI describes an API in a machine-readable way, so tools can generate documentation, client code, and tests from a single source of truth.

Common API Design Mistakes

Inconsistent or action-heavy URLs.
Wrong status codes.
Leaking internal error details.
No validation or pagination.
Confusing authentication with authorization.
Inconsistent response structures.

Syntax

A small RESTful FastAPI examplepython

1from fastapi import FastAPI, HTTPException2 3app = FastAPI()4posts = {}5 6@app.get("/posts/{post_id}")7def get_post(post_id: int):8    if post_id not in posts:9        raise HTTPException(status_code=404, detail="post not found")10    return posts[post_id]11 12@app.post("/posts", status_code=201)13def create_post(title: str):14    if not title:15        raise HTTPException(status_code=400, detail="title is required")16    return {"id": len(posts) + 1, "title": title}

Note the correct status codes: 201 for created, 404 for missing, 400 for invalid input.

Examples

Request and response

A client creates a post and the server returns 201.

text

1POST /posts2{ "title": "Hello" }

Output

201 Created
{ "id": 1, "title": "Hello" }

Not found

Requesting a missing resource returns 404.

text

1GET /posts/999

Output

404 Not Found

Key Takeaways

REST is an architectural style centered on resources and a uniform interface.
Design URLs around nouns (resources), not actions.
Use HTTP methods and status codes consistently and correctly.
Validate input and return consistent error responses.
Authenticate identity; authorize permissions.
Document the API with OpenAPI so tools can generate docs and clients.

← PreviousBackend Fundamentals Next →Databases & ORMs