API REST e Insomnia

Arcane.API — OpenAPI, coleção do Insomnia, Postman e curl, derivados das rotas do Kiln.

O Kiln já é um framework REST completo: route, resource, cors, auth, rate_limit, paginação, validação. O que faltava era o outro lado — quem vai consumir a API precisava ler o código-fonte do servidor para saber o que ela oferece.

Um comando#

dataforge api src/app.df                          # a tabela de rotas
dataforge api src/app.df --openapi  -o=openapi.json
dataforge api src/app.df --insomnia -o=insomnia.json
dataforge api src/app.df --postman  -o=postman.json
dataforge api src/app.df --curl

Insomnia#

Importar em Import → From File dá uma requisição por rota, já com método, URL e corpo de exemplo onde faz sentido.

dataforge api src/app.df --insomnia -o=insomnia.json

Deixar :id cru daria uma requisição que bate literalmente em /produtos/:id — e ninguém entende por que dá 404.

OpenAPI 3.1#

É o formato que o Swagger UI lê, que gera cliente em vinte linguagens, e que um validador de contrato consome. Se for para exportar um só, é este.

adopt Kiln
adopt Arcane.API as API

server Loja on 8080:
    route GET "/produtos":
        respond json {"produtos": []}
    route POST "/produtos":
        respond json {"criado": yes}
    route GET "/produtos/:id":
        respond json {"id": params["id"]}

out API.openapi(Loja, {
    "titulo": "API da Loja",
    "versao": "2.0.0",
    "base": "https://api.loja.com"
})

/produtos/:id vira /produtos/{id}, e o parâmetro de caminho é declarado. Sem essa tradução, o Swagger trata :id como parte literal do caminho e o cliente gerado bate numa URL que não existe.

curl, para o README#

# Lista produtos
curl https://api.loja.com/produtos

# Cria produtos
curl -X POST https://api.loja.com/produtos \
  -H 'Content-Type: application/json' \
  -d '{}'

# Um produto
curl https://api.loja.com/produtos/<id>

É o formato menos cerimonioso, e o que mais se usa na prática: cabe num README, num chamado de suporte, ou numa mensagem para quem está testando a API pela primeira vez.

A tabela inteira#

O config aceita titulo, versao, descricao e base. Todas as funções aceitam tanto o servidor quanto a lista que Kiln.routes devolve — quem chama não deveria precisar saber qual das duas tem em mãos.

O que ele não infere, e por quê#

O Kiln não declara tipos de corpo nem de resposta: respond json {…} monta o vault na hora. Então o esquema de entrada e saída não aparece no OpenAPI — só a rota, o método e os parâmetros de caminho.

Onde você declarar validação com Kiln.validar, essa parte é real e entra.