Especificación OpenAPI

Toda esta referencia se genera a partir de un único archivo OpenAPI 3.0.3, que puedes descargar y usar en tus propias herramientas.

Descargar openapi.yaml

Generar un cliente

TypeScript

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.joinotify.com/openapi.yaml \
  -g typescript-fetch \
  -o ./src/joinotify

Python

npx @openapitools/openapi-generator-cli generate \
  -i https://docs.joinotify.com/openapi.yaml \
  -g python \
  -o ./joinotify_client

Solo los tipos, en TypeScript

npx openapi-typescript https://docs.joinotify.com/openapi.yaml -o ./src/joinotify.d.ts

Importar en Postman o Insomnia

Postman — el camino más corto es la colección lista, con cuerpos de ejemplo e ids que pasan de una llamada a la siguiente. Para generarla a partir de la spec: Import → Link → pega https://docs.joinotify.com/openapi.yaml. Después, crea una variable de entorno token y configura la autorización de la colección como Bearer Token apuntando a ella.

Insomnia — Create → Import From → URL, la misma URL.

Extensiones propietarias

Extensión	Significado
x-joinotify-status: planned	El endpoint está documentado pero todavía no está activo

Si generas código a partir del spec, conviene filtrar las operaciones marcadas así — hoy responden 404.

Quitar los endpoints planificados antes de generar

npx js-yaml openapi.yaml \
| jq 'del(.paths[] | .[] | select(.["x-joinotify-status"] == "planned"))' \
> openapi-disponible.json

Versionado

El spec sigue la versión de la API, hoy 1.0.0. Los cambios que rompen el contrato — eliminar un campo, cambiar un tipo, volver obligatorio uno opcional — solo ocurren en una versión mayor, avisada con antelación.

Añadir un campo opcional a una respuesta no se considera una ruptura. Tu cliente debe ignorar los campos desconocidos en lugar de fallar con ellos.

Dónde difieren el spec y el espejo /v1

Las operaciones bajo /v1 describen el contrato de Meta, y sus cuerpos de respuesta están tipados como objeto libre a propósito: reenviamos la respuesta de Meta byte a byte, y esta cambia entre versiones de la Graph API.

Si necesitas los tipos exactos de esas rutas, la fuente es la documentación de Meta, no este spec.