RESTFUL API

A RESTful API is an API that follows the ideas of REST (Representational State Transfer). You expose resources (e.g. users, orders, products) as URLs, and clients use standard HTTP methods to read or change them. The server doesn’t keep client state between requests; each request carries what’s needed.

Resources and URLs

Everything you can access is a resource, identified by a URL (path). Use nouns, not verbs: /users, /orders/123, /products. The same URL can represent a collection (/users) or a single item (/users/42). Keep URLs clear and hierarchical.

HTTP methods

Clients say what they want to do with the resource by choosing the right method:

• GET – Read a resource or list. No body; safe and repeatable. Example: get user 42 → GET /users/42.
• POST – Create a new resource. Body usually contains the data. Example: create user → POST /users with JSON body.
• PUT – Replace a resource (full update). Example: PUT /users/42 with full user object.
• PATCH – Partial update. Send only the fields to change. Example: PATCH /users/42 with {"name": "New Name"}.
• DELETE – Remove a resource. Example: DELETE /users/42.

Status codes

The server responds with an HTTP status code so the client knows the outcome:

1xx Informational

• 100 Continue – Client may send the request body; server will accept it. Used when the client asks with Expect: 100-continue (e.g. before a large POST).
• 101 Switching Protocols – Server agrees to switch protocol (e.g. upgrade to WebSocket).

2xx Success

• 200 OK – Request succeeded (e.g. GET, PATCH).
• 201 Created – Resource created (e.g. after POST); often include the new resource or its URL in the response.
• 204 No Content – Success with no body (e.g. after DELETE).

3xx Redirection

• 301 Moved Permanently – Resource has a new URL; client should use the new URL from Location for future requests. Caches may update.
• 302 Found – Temporary redirect. Client should follow Location for this request; original URL may still be valid later.
• 303 See Other – Redirect after POST (e.g. form submit). Client should use GET on the Location URL to fetch the result.
• 304 Not Modified – Conditional GET: resource unchanged; client can use its cached copy. Sent when If-None-Match or If-Modified-Since matches.
• 307 Temporary Redirect – Same as 302 but the client must keep the same HTTP method when following the redirect.
• 308 Permanent Redirect – Same as 301 but the client must keep the same HTTP method when following the redirect.

4xx Client error / 5xx Server error

• 400 Bad Request – Invalid input or malformed request.
• 401 Unauthorized – Not authenticated (e.g. missing or invalid token).
• 403 Forbidden – Authenticated but not allowed to do this action.
• 404 Not Found – Resource or URL doesn’t exist.
• 500 Internal Server Error – Server-side failure.

Statelessness

Each request is independent. The server doesn’t store client “sessions” for REST; any auth or context is sent in the request (e.g. headers like Authorization). That makes the API easy to scale and reason about.

Summary

Design your API around resources and URLs, use GET/POST/PUT/PATCH/DELETE correctly, return the right status codes, and keep the server stateless. That’s the core of a RESTful API.