Documentação — Fake API

git clone https://github.com/samuelikz/fakeapi.git
cd fakeapi

npm install

cp env.example .env
# ajuste as variáveis conforme necessário

npm run dev   # http://localhost:8000
# ou:
npm run build && npm start

⚙️ Configuração (.env)

Variável	Padrão	Descrição
`NODE_ENV`	`development`	Ambiente de execução.
`PORT`	`8000`	Porta HTTP.
`DB_PATH`	`./data/db.json`	Arquivo JSON do banco.
`CORS_ORIGIN`	`*` (dev)	Origens permitidas via CORS.
`AUTH_ENABLED`	`false`	Ativa o modo Mock JWT (quando `true` exige Bearer em rotas protegidas).
`AUTH_JWT_SECRET`	`dev-secret`	Segredo para assinar/verificar JWT.
`AUTH_TOKEN_TTL`	`1h`	Validade do token (ex.: `15m`, `1h`, `7d`).

🧭 Endpoints (Health, Sistema, CRUD)

Auth (Mock JWT)

POST /auth/login — login fake; retorna { token, user }
POST /auth/refresh — renova token fake; retorna novo { token, user }

Health

Método	Endpoint	Descrição
`GET`	`/health`	Health básico.
`GET`	`/health/detailed`	Detalhes de sistema, app e banco.
`GET`	`/health/ping`	Ping simples (pong).
`GET`	`/health/ready`	Readiness (pronto p/ tráfego).
`GET`	`/health/live`	Liveness.
`GET`	`/_health`	Alternativo/compat.

Sistema

GET /__resources — lista recursos e contagem.
GET /_docs — documentação embutida.
POST /_ensure/:resource — cria recurso se não existir.
POST /_reset — reseta o banco (dev).

CRUD dinâmico

GET /:resource — lista com paginação/filtros
GET /:resource/:id — obtém item
POST /:resource — cria item
PUT /:resource/:id — atualiza total
PATCH /:resource/:id — atualiza parcial
DELETE /:resource/:id — remove

🔐 Autenticação Mock JWT

Modo opcional para prototipagem e testes. Não usar em produção sem segurança real.

.env necessários

AUTH_ENABLED=true
AUTH_JWT_SECRET=uma_senha_bem_grande_e_secreta
AUTH_TOKEN_TTL=1h
# Opcional
# DB_PATH=./data/db.json

Exemplo de users em `db.json`

JSON

{
  "users": [
    { "id": 1, "email": "[email protected]", "name": "Admin", "password": "admin123", "role": "admin", "scopes": ["*:*"] },
    { "id": 2, "email": "[email protected]", "name": "Alice", "password": "alice", "role": "user", "scopes": ["read:*"] }
  ],
  "posts": []
}

Login e uso do token

curl -sX POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"admin123"}'

TOKEN="cole_aqui"
curl -s http://localhost:8000/posts -H "Authorization: Bearer $TOKEN"

Política de escopos (CRUD)

read:<resource> → GET /:resource
create:<resource> → POST /:resource
update:<resource> → PUT/PATCH /:resource/:id
delete:<resource> → DELETE /:resource/:id

Curingas: read:* (leitura global), *:* (admin total).

🔎 Parâmetros de consulta

_page — página (padrão: 1)
_limit — itens por página (padrão: 50, máx.: 100)
_meta — metadados de paginação (0 ou 1)
q — busca textual em todos os campos

GET /posts?q=node&_page=2&_limit=10&_meta=1

🧪 Exemplos (cURL / fetch)

curl -s http://localhost:8000/posts | jq

curl -s "http://localhost:8000/posts?q=node&_page=2&_limit=10&_meta=1" | jq

curl -s -X POST http://localhost:8000/posts \
  -H 'Content-Type: application/json' \
  -d '{"title":"Bem-vindo à Fake API","content":"API RESTful com arquitetura limpa.","author":"Samuel","tags":["api","rest","nodejs"]}' | jq

fetch('http://localhost:8000/posts')
  .then(r => r.json())
  .then(console.log)

fetch('http://localhost:8000/posts?q=node&_page=2&_limit=10&_meta=1')
  .then(r => r.json())
  .then(console.log)

fetch('http://localhost:8000/posts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    title: 'Bem-vindo à Fake API',
    content: 'API RESTful com arquitetura limpa.',
    author: 'Samuel',
    tags: ['api','rest','nodejs']
  })
}).then(r => r.json()).then(console.log)

📬 Status Codes

200 OK — sucesso
201 Created — item criado
204 No Content — removido / sem corpo
400 Bad Request — parâmetros inválidos
401 Unauthorized — token inválido/ausente
403 Forbidden — escopo insuficiente
404 Not Found — recurso/ID inexistente
422 Unprocessable Entity — validação falhou
500 Internal Server Error — erro interno
503 Service Unavailable — não saudável

🗂️ Estrutura do banco

JSON

{
  "posts": [
    {
      "id": 1,
      "title": "Bem-vindo à Fake API",
      "content": "Esta é uma API RESTful completa com arquitetura limpa e separação de responsabilidades.",
      "author": "Samuel",
      "tags": ["api","rest","nodejs"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ],
  "users": [
    {
      "id": 1,
      "email": "[email protected]",
      "name": "Admin",
      "password": "admin123",
      "role": "admin",
      "scopes": ["*:*"],
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

🏗️ Arquitetura

src/
├─ auth/             # mock JWT (jwt, guard, scopes, req.user)
├─ config/           # app & database config
├─ controllers/      # health, resource, system
├─ middleware/       # cors, logger, validation
├─ routes/           # auth, health, resource, system
├─ services/         # database service
├─ utils/            # file utils
└─ server.js         # bootstrap da aplicação

Caminho	Arquivo	Função
src/auth	`jwt.js`	Assina/verifica tokens JWT.
src/auth	`mw-auth.js`	Popula `req.user` quando Bearer válido.
src/auth	`guard.js`	Exige escopos por rota (403 se faltar).
src/auth	`crud-policy.js`	Mapeia método HTTP → `read/create/update/delete`.
src/auth	`user-store-file.js`	Lê usuários do `db.json`.
src/routes	`auth.routes.js`	Endpoints `/auth/login` e `/auth/refresh`.

📑 Logs & Erros

[2024-01-01T00:00:00.000Z] GET /posts - Started
[2024-01-01T00:00:00.000Z] 🟢 GET /posts -> 200 (15ms)
[2024-01-01T00:00:00.000Z] 🔴 POST /posts -> 400 (8ms)
[2024-01-01T00:00:00.000Z] 💚 GET /health -> 200 (5ms)

JSON

{
  "error": "Bad Request",
  "message": "Invalid ID parameter. ID must be a positive number."
}

🖥️ Interface Web

/ — home com passos de uso e exemplos
/_docs — documentação embutida

🤝 Contribuindo

Faça fork do repositório
Crie branch: git checkout -b feature/minha-feature
Commits descritivos e testes
Abra um Pull Request

📄 Licença

Licenciado sob MIT. Veja LICENSE.

❓ FAQ

Posso usar em produção?

Não recomendado. É voltado a desenvolvimento, testes e protótipos.

Como restringir CORS?

Defina CORS_ORIGIN com suas origens. Evite * fora de dev.

Documentação — Fake API

Instalação rápida

Configuração

Endpoints

Mock JWT

Parâmetros

Arquitetura

Auth (Mock JWT)

Health

Sistema

CRUD dinâmico

.env necessários

Exemplo de users em db.json

Login e uso do token

Política de escopos (CRUD)

Exemplo de users em `db.json`