Beginner System Architecture

REST APIs

REST (Representational State Transfer) is the most common style for building web APIs. It models your system as a set of resources, addresses them with URLs, and acts on them with standard HTTP verbs. Its strength is simplicity: it reuses the web’s own rules instead of inventing new ones.

Resources and URLs

A resource is a thing: a user, an order, a product. Name resources with plural nouns, never verbs.

Good:  /users           /users/42        /users/42/orders
Bad:   /getUser         /createUser      /user_list

The URL identifies the resource. The verb says what to do with it.

HTTP verbs

GET    /users        read the list
GET    /users/42     read one user
POST   /users        create a new user
PUT    /users/42     replace user 42
PATCH  /users/42     update part of user 42
DELETE /users/42     delete user 42

A full exchange

POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json

{ "name": "Ada", "email": "ada@example.com" }
HTTP/1.1 201 Created
Location: /v1/users/42
Content-Type: application/json

{ "id": 42, "name": "Ada" }

Status codes

Use the right code so clients know what happened.

200 OK            success with a body
201 Created       resource created
204 No Content    success, nothing to return
400 Bad Request   malformed input
401 Unauthorized  not authenticated
403 Forbidden     authenticated but not allowed
404 Not Found     resource does not exist
409 Conflict      state conflict (e.g. duplicate)
422 Unprocessable validation failed
500 Server Error  the server broke

Stateless

Each request must carry everything the server needs, like an auth token. The server keeps no client session between requests. This makes REST easy to scale horizontally, since any server can handle any request.

Best practices

  • Version your API: /v1/.
  • Use query strings for filtering, sorting, and pagination: /users?sort=name&page=2.
  • Return clear JSON errors, never raw stack traces.
  • Keep PUT and DELETE idempotent: repeating them has the same effect.

When to use it

REST is a great default for public web services and CRUD-style systems. If clients need very flexible queries, consider GraphQL; for high-performance internal calls, consider gRPC.