REST API Basics

Understand the request, the response, and the resource.

REST is a clean way for one system to ask another system for data or to send data. The browser, app, or script sends an HTTP request to an endpoint. The server processes it and sends back a response, usually in JSON.

Hub Intermediate Advanced MySQL + JSON Labs Challenges

REST as architecture, not just JSON over HTTP

REST is an architectural style. The main idea is not "return JSON", but to design systems around resources, standard HTTP semantics, stateless requests, cacheable responses, and intermediaries that can improve scalability and security.

Practical reality

Many real APIs are HTTP resource APIs that follow REST strongly without implementing full hypermedia navigation everywhere. That is common in production. What matters most is consistent resource design and correct HTTP behavior.

Resource

The thing you are working with, such as users, campaigns, orders, reports, or products.

Representation

The serialized form of resource state, usually JSON, labeled by a media type such as `application/json`.

Endpoint

The URL that represents a resource or action, such as `/api/campaigns` or `/api/orders/17`.

Method

The HTTP verb that tells the server what you want to do: GET, POST, PUT, PATCH, or DELETE.

Statelessness

Each request should contain enough context to be processed correctly without relying on hidden server-side session state.

Uniform interface

Clients use consistent HTTP semantics instead of custom remote method names for every operation.

Headers

Metadata about the call such as content type, authorization token, request id, or API version.

Body

The JSON payload sent with POST, PUT, or PATCH when you create or update data.

Response

The JSON and status code returned by the server after it processes the request.

HTTP methods

Method Example endpoint Meaning
GET /api/articles Read a list of articles
GET /api/articles/25 Read one article
POST /api/articles Create a new article
PUT /api/articles/25 Replace the entire article
PATCH /api/articles/25 Update one or two fields only
DELETE /api/articles/25 Delete the article

Common status codes

Code Meaning
200 OK The request worked and the server returned data.
201 Created A new record was created successfully.
204 No Content The request worked, but there is no body to return.
400 Bad Request The input was wrong or missing required fields.
401 Unauthorized Auth is missing or invalid.
403 Forbidden The user is authenticated but not allowed to do this action.
404 Not Found The endpoint or record does not exist.
409 Conflict There is a duplicate or version conflict.
429 Too Many Requests The client hit the rate limit.
500 Internal Server Error The server failed while processing the request.

How to read a request

  • Start with the method. It tells you whether the client wants to read, create, replace, update, or delete.
  • Read the endpoint next. `/api/orders/17` means one order. `/api/orders` usually means a list or a create action.
  • Check headers for auth, content type, request id, and versioning.
  • Inspect the body only when the call sends JSON, usually in POST, PUT, or PATCH.

How to read a response

  • Check the status code first so you know whether the call worked or failed.
  • Then inspect the JSON body for `data`, `error`, `message`, `pagination`, or `meta` fields.
  • If something fails, compare the exact request body with the API documentation before retrying.
  • Save the request id or trace id if the backend provides one. It helps support teams locate the call in logs.

Conditional requests and concurrency

  • When multiple clients can edit the same row, one update can overwrite another unless the API checks a validator.
  • ETag is a common validator. Clients can send `If-None-Match` for cache validation and conditional operations.
  • This helps prevent mid-air collisions and avoids serving stale content when the resource changed.

Pragmatic CRUD mapping

  • `GET /items` lists resources and `GET /items/{id}` reads one resource.
  • `POST /items` creates a resource, while `PATCH /items/{id}` updates only the fields you send.
  • `PUT /items/{id}` is best for full replacement and `DELETE /items/{id}` is idempotent by design.

Simple real-life example

A website wants to save a lead form submission. The frontend sends a `POST` request to `/api/leads`. The backend validates the fields, stores the row in a database, and returns JSON with the newly created record.

curl request

curl -X POST https://example.com/api/leads \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "name": "Asha",
    "email": "asha@example.com",
    "source": "landing-page"
  }'

JSON response

{
  "success": true,
  "data": {
    "id": 101,
    "name": "Asha",
    "email": "asha@example.com",
    "source": "landing-page",
    "created_at": "2026-03-25T10:45:00Z"
  }
}