📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados em Módulo 07: Backend e APIs. Recomendado revisar antes de começar.

🌐 Arquitetura de APIs RESTful, Richardson Maturity & OpenAPI 3.0

v1.0 — Design de APIs, HATEOAS, OpenAPI 3.0 / Swagger e RFC 7807

Trilha de Especialização Pedagógica — Projeto 1 de 4

• ➡️ v1 (este): Fundamentos de Backend · RESTful Design · Richardson Nível 3 · OpenAPI 3.0 · RFC 7807
• v2: Autenticação Stateless com JWT e Refresh Tokens
• v3: GraphQL Federation & Subscriptions em Tempo Real
• v4: Arquitetura de Microsserviços com API Gateway e Service Mesh

🎓 Nível Profissional Simulado: Engenheiro de Backend Júnior / Pleno. Criar uma API não é apenas responder um JSON com status 200 para tudo. Um arquiteto de backend domina os verbos HTTP semânticos (GET, POST, PUT, PATCH, DELETE), códigos de status (201, 204, 400, 404, 409, 422), paginação por cursor, contratos OpenAPI 3.0 e hipermídia HATEOAS.

🎯 Objetivo & Escopo do Projeto

Projetar e documentar uma API RESTful Corporativa de Pedidos e Catálogo no Nível 3 do Modelo de Maturidade de Richardson, com hipermídia HATEOAS, documentação interativa via OpenAPI 3.0 / Swagger, paginação eficiente e padronização de tratamento de erros no formato RFC 7807 (Problem Details).

🧑‍💼 Fase 1 — Levantamento de Requisitos

O Briefing do Cliente (Arquiteto de Integração B2B)

“Nossos parceiros comerciais precisam se integrar com nossa API de pedidos. Eles reclamam que a API antiga usava POST para tudo e devolvia status 200 mesmo quando dava erro no banco. Queremos uma API RESTful impecável: rotas plurais (/api/v1/pedidos), verbos corretos, códigos HTTP semânticos, links HATEOAS para ações seguintes (cancelar, pagar) e documentação Swagger onde o desenvolvedor possa testar no navegador.”

Requisitos Funcionais (RF) e Não-Funcionais (RNF)

📋 Fase 2 — Backlog & User Stories

🌿 Fase 3 — Engenharia em Equipe (Git Flow & Setup)

# Branch da funcionalidade
git checkout -b feature/US01-openapi-spec

# Visualizar o contrato OpenAPI 3.0
cat api_spec.yaml

🛠️ Fase 4 — Implementação do Contrato OpenAPI & Resposta HATEOAS

Payload HATEOAS Padronizado (GET /api/v1/pedidos/101)

{
  "id": 101,
  "cliente": "Empresa ABC Ltda",
  "status": "PENDENTE_PAGAMENTO",
  "valorTotal": 4500.00,
  "_links": {
    "self": { "href": "/api/v1/pedidos/101" },
    "pagar": { "href": "/api/v1/pedidos/101/pagamentos", "method": "POST" },
    "cancelar": { "href": "/api/v1/pedidos/101/cancelar", "method": "PUT" }
  }
}

🚀 Como Executar no Laboratório

1. Abra o terminal na pasta deste projeto

No seu editor/IDE, abra a pasta deste projeto (File > Open Folder) ou navegue via terminal:

cd backend_01_rest_api_architecture

2. Execute a aplicação ou testes

# Executar comandos específicos da tecnologia:
python main.py # ou npm run dev / ./gradlew build

[!TIP] Dica para execução a partir da raiz do repositório: Se você abriu o repositório completo no VS Code, basta navegar até a pasta antes de executar: cd catalogo_projetos/backend_01_rest_api_architecture`

🧭 Decisões de Arquitetura (ADRs)

• ADR 001: Adoção do Modelo Richardson Nível 3 e OpenAPI 3.0 para padronização corporativa.

🧪 Testes de Validação & Asserções

# Validar se o contrato YAML está estritamente em conformidade com OpenAPI 3.0
npx @redocly/cli lint api_spec.yaml

🏛️ Arquitetura Visual & Engenharia do Sistema

O diagrama abaixo sintetiza a organização dos artefatos, contratos e diretrizes arquiteturais na subpasta openapi/:

flowchart TD
    subgraph Especificacao["Especificação & Contratos"]
        E1["Contratos Formais"] --> E2["Modelagem de Domínio"]
    end
    subgraph Implementacao["Implementação & Stacks"]
        I1["Arquiteturas & Código"] --> I2["Paridade Multilinguagem"]
    end
    subgraph Padroes["Governança & Padrões"]
        P1["Living Styleguides"] --> P2["Conformidade de Design"]
    end
    subgraph Homologacao["Qualidade & Homologação"]
        Q1["Matriz de Rastreabilidade"] --> Q2["Checkpoints CP-01..05 PASS"]
    end

    Especificacao --> Implementacao
    Implementacao --> Padroes
    Padroes --> Homologacao

    style Especificacao fill:#e3f2fd,stroke:#1976d2,stroke-width:1.5px
    style Implementacao fill:#fffde7,stroke:#fbc02d,stroke-width:1.5px
    style Padroes fill:#e8f5e9,stroke:#388e3c,stroke-width:1.5px
    style Homologacao fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1.5px

🎯 Engenharia de Requisitos & Modelagem Formal

👤 User Stories (Histórias de Usuário)

⚙️ Requisitos Funcionais (RF)

🛡️ Requisitos Não-Funcionais (RNF)

🔗 Matriz de Rastreabilidade (RTM)

🏁 Checkpoints de Qualidade & Homologação