API Design & REST

REST Fundamentals

30 min

An API (application programming interface) lets programs talk to your application: a mobile app, a frontend, a partner's server or a no-code automation. REST is the most common style for web APIs: everything is a resource identified by a URL, manipulated with standard HTTP methods.

Resources and URLs

Use nouns, plural, lowercase, with hyphens:

GET    /v1/projects                 list projects
POST   /v1/projects                 create a project
GET    /v1/projects/42              get one project
PATCH  /v1/projects/42              update part of it
DELETE /v1/projects/42              delete it
GET    /v1/projects/42/reviews      reviews belonging to project 42

Avoid verbs in URLs (/getProjects, /deleteProject?id=42). For actions that are not simple CRUD, use a sub-resource: POST /v1/orders/7/refunds.

Methods and their meaning

Method Purpose Safe Idempotent
GET read yes yes
POST create / action no no
PUT replace entirely no yes
PATCH partial update no usually
DELETE remove no yes

Safe means no side effects (GET must never change data). Idempotent means repeating the request has the same effect as doing it once, which matters when clients retry after timeouts.

Status codes

Code Use when
200 OK successful read or update
201 Created resource created (include a Location header)
204 No Content success with no body (often DELETE)
400 Bad Request malformed input
401 Unauthorized missing or invalid credentials
403 Forbidden authenticated but not allowed
404 Not Found does not exist (or you should not know it does)
409 Conflict duplicate, or a state conflict
422 Unprocessable Entity valid JSON but failed validation
429 Too Many Requests rate limited (include Retry-After)
500 / 503 server error / temporarily unavailable

JSON conventions

Pick one style and use it everywhere: snake_case or camelCase keys, ISO 8601 dates in UTC ("2026-10-21T09:30:00Z"), money as integer minor units plus a currency code, and IDs as strings if they may exceed JavaScript's safe integer range.

{
  "id": "42",
  "title": "Salon booking app",
  "price": {"amount": 4900, "currency": "usd"},
  "created_at": "2026-10-21T09:30:00Z"
}

Check yourself

  • Why should GET never change data?
  • What is the difference between 401 and 403?
  • How should an API represent money?

Seu progresso fica salvo apenas neste navegador.

Enviar para revisão (10 pontos)