Especificação OpenAPI
Toda esta referência é gerada de um único arquivo OpenAPI 3.0.3, que você pode baixar e usar nas suas próprias ferramentas.
Baixar openapi.yaml
Gerando um cliente
npx @openapitools/openapi-generator-cli generate \
-i https://docs.joinotify.com/openapi.yaml \
-g typescript-fetch \
-o ./src/joinotify
npx @openapitools/openapi-generator-cli generate \
-i https://docs.joinotify.com/openapi.yaml \
-g python \
-o ./joinotify_client
npx openapi-typescript https://docs.joinotify.com/openapi.yaml -o ./src/joinotify.d.ts
Importando no Postman ou Insomnia
Postman — o caminho mais curto é a collection pronta, com corpos de
exemplo e ids que passam de uma chamada para a outra. Para gerar a partir da spec: Import →
Link → cole https://docs.joinotify.com/openapi.yaml. Depois, crie uma variável de
ambiente token e configure a autorização da coleção como Bearer Token apontando para ela.
Insomnia — Create → Import From → URL, mesma URL.
Extensões proprietárias
| Extensão | Significado |
|---|---|
x-joinotify-status: planned | O endpoint está documentado mas ainda não está no ar |
Se você gera código a partir da spec, vale filtrar as operações marcadas assim — elas vão
responder 404 hoje.
npx js-yaml openapi.yaml \
| jq 'del(.paths[] | .[] | select(.["x-joinotify-status"] == "planned"))' \
> openapi-disponivel.json
Versionamento
A spec segue a versão da API, hoje 1.0.0. Mudanças que quebram contrato — remover campo,
mudar tipo, tornar opcional obrigatório — só acontecem em uma versão maior, com aviso
prévio.
Adicionar campo opcional na resposta não é considerado quebra. Seu cliente precisa ignorar campos desconhecidos em vez de falhar com eles.
Diferenças entre a spec e o espelho /v1
As operações sob /v1 descrevem o contrato da Meta, e os corpos de resposta estão
tipados como objeto livre de propósito: nós repassamos a resposta da Meta byte a byte, e
ela muda entre versões da Graph API.
Se você precisa dos tipos exatos dessas rotas, a fonte é a documentação da Meta, não esta spec.