What is REST API?

A REST API is an interface that follows the principles of REST (Representational State Transfer), the architectural style described by Roy Fielding in 2000. The core idea is simple: everything in the system is treated as a resource, each resource has an address (a URL), and actions on it are expressed through HTTP’s own methods.

This means the URL identifies what and the method says what to do. Instead of inventing endpoints like /createUser and /deleteUser, you have a single /usuarios resource and vary the verb.

The HTTP verbs and what each one means

GET    /usuarios        # list all
GET    /usuarios/42     # fetch a specific one
POST   /usuarios        # create a new one
PUT    /usuarios/42     # replace it entirely
PATCH  /usuarios/42     # change only some fields
DELETE /usuarios/42     # remove it

Two of these verbs deserve special attention. GET must be safe: calling it cannot change anything on the server. And PUT and DELETE must be idempotent — repeating the same call ten times has to produce the same result as calling it once. That is what lets a client safely retry when the network fails.

The principles that define REST

• Client-server — the two ends evolve independently, as long as the contract holds.
• Stateless — each request carries everything the server needs to answer it. The server keeps no session between calls.
• Cacheable — responses indicate whether and for how long they can be reused, which reduces load and latency.
• Uniform interface — the same URL patterns, verbs and codes apply to every resource in the API.
• Layered system — proxies, load balancers and CDNs can sit in the path without the client having to know.

Status codes: the answer before the body

The HTTP status communicates the outcome before you even read the JSON. Using them correctly is what separates a well-built API from one that returns 200 OK with {"error": true} inside.

• 2xx — it worked. 200 for general success, 201 for a created resource, 204 when there is no body to return.
• 4xx — the client made the mistake. 400 malformed request, 401 not authenticated, 403 authenticated but not allowed, 404 does not exist, 429 too many calls.
• 5xx — the server failed. 500 internal error, 503 service unavailable.

Best practices when designing one

Use plural nouns for resources (/products, not /product or /getProducts). Version the API from day one (/v1/products), because breaking changes are inevitable. Paginate long lists instead of returning ten thousand records at once. And standardize the error format so the client does not have to guess the structure at every endpoint. When working with responses, the JSON formatter helps you inspect large payloads.