Fundamentos de API e HTTP

O que é uma API?

API (Application Programming Interface) é um contrato entre sistemas. APIs Web expõem funcionalidades via HTTP.

Cliente → Request HTTP → API Server → Response HTTP → Cliente

HTTP Methods

Method	CRUD	Idempotente	Safe	Body
GET	Read	Sim	Sim	Não
POST	Create	Não	Não	Sim
PUT	Replace	Sim	Não	Sim
PATCH	Partial Update	Não*	Não	Sim
DELETE	Delete	Sim	Não	Opcional

HTTP Status Codes

1xx: Informational
├── 101: Switching Protocols (WebSocket)

2xx: Success
├── 200 OK
├── 201 Created
├── 202 Accepted   (async processing)
├── 204 No Content (DELETE bem-sucedido)

3xx: Redirection
├── 301 Moved Permanently
├── 302 Found (temporary)
├── 304 Not Modified (cache)
├── 307 Temporary Redirect (mesmo método)
├── 308 Permanent Redirect (mesmo método)

4xx: Client Error
├── 400 Bad Request
├── 401 Unauthorized
├── 403 Forbidden
├── 404 Not Found
├── 405 Method Not Allowed
├── 409 Conflict
├── 422 Unprocessable Entity (validation)
├── 429 Too Many Requests (rate limit)

5xx: Server Error
├── 500 Internal Server Error
├── 502 Bad Gateway
├── 503 Service Unavailable
├── 504 Gateway Timeout

REST — Representational State Transfer

Princípios REST (Roy Fielding):

1. Stateless: cada request contém toda info necessária
2. Cacheable: responses marcadas como cacheáveis ou não
3. Uniform Interface: recursos identificados por URL
4. Layered System: cliente não sabe se fala com servidor ou proxy
5. Code on Demand (opcional): scripts executáveis

Endpoints RESTful

# Recursos (substantivos, plurais)
GET    /api/v1/users          → lista usuários
POST   /api/v1/users          → cria usuário
GET    /api/v1/users/:id      → detalhe usuário
PUT    /api/v1/users/:id      → substitui usuário
PATCH  /api/v1/users/:id      → atualiza parcial
DELETE /api/v1/users/:id      → deleta usuário

# Relacionamentos
GET    /api/v1/users/:id/orders   → pedidos do usuário
GET    /api/v1/users/:id/orders/:orderId  → pedido específico

# Filtros, ordenação, paginação
GET /api/v1/users?status=active&sort=-created_at&page=2&limit=20

# Testar API com curl
curl -X GET https://api.github.com/users/octocat

curl -X POST https://api.exemplo.com/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer token123" \
  -d '{"name": "João", "email": "[email protected]"}'

curl -X DELETE https://api.exemplo.com/users/123

OpenAPI / Swagger

openapi: 3.0.0
info:
  title: Users API
  version: 1.0.0
paths:
  /users:
    get:
      summary: Lista usuários
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        200:
          description: Lista de usuários
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      summary: Cria usuário
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        201:
          description: Usuário criado
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        email:
          type: string
          format: email

REST é um conjunto de constraints, não um padrão. Use substantivos plurais para recursos. Versionamento via URL (/v1/). OpenAPI é o padrão para documentação de APIs REST.