Colección de Postman y documento OpenAPI

KeenAuth publica su contrato de API legible por máquina en dos archivos. Ambos se generan a partir de la definición pública de la API de gestión en cada versión, por lo que siempre coinciden con la referencia de la API. Las operaciones internas nunca aparecen en ellos.

Archivo Formato Descarga
Colección de Postman Postman Collection v2.1.0 postman_collection.json
Documento OpenAPI OpenAPI 3.1 openapi.json

Importar en Postman

  1. En Postman, elija Import y seleccione el archivo postman_collection.json descargado.
  2. Abra las variables de la colección y establezca apiKey con una clave de la API de gestión. Cree una en el panel de control o con la CLI; la clave se envía como token Bearer.
  3. Establezca region con la región de su entorno (eu es el valor predeterminado). Las solicitudes se envían al host api.{{region}}.keenauth.com, ruta /v1.
  4. Envíe una solicitud. Cada solicitud POST incluye un encabezado Idempotency-Key que Postman completa con un GUID nuevo, por lo que reintentar una solicitud es seguro.

Las solicitudes se agrupan en una carpeta por cada etiqueta de la API. Los parámetros de ruta, como {{user_id}}, son variables de la colección: establézcalos antes de enviar una solicitud que los necesite.

Usar el documento OpenAPI

El documento OpenAPI es la entrada para la generación de código y para gateways de API, linters y servidores simulados. La propia API sirve el mismo documento en https://api.eu.keenauth.com/v1/openapi.json.

Archivo del contrato y digests de los SDK

El documento OpenAPI también se publica en una ruta de archivo direccionada por contenido. El segmento de la ruta es el SHA-256 de los bytes del documento, por lo que el archivo en una ruta de archivo nunca cambia:

Archivo Contenido
/openapi/<sha256>/openapi.json El documento, idéntico byte a byte a /api/openapi.json de esa versión
/openapi/<sha256>/openapi.json.sha256 El digest en formato sha256sum
/openapi/index.json Los documentos archivados: sha256, info_version, path; current marca el más reciente

Cada SDK de servidor registra el digest del documento a partir del cual se generó:

SDK Dónde
Node.js (@keenauth/node) Exportación OPENAPI_SHA256 y keenauth.openapiSha256 en package.json
Python (keenauth-python) keenauth.OPENAPI_SHA256 y la URL del proyecto OpenAPI document en los metadatos del paquete
Go keenauth.OpenAPISHA256

Para comprobar una descarga, ejecute sha256sum -c openapi.json.sha256 en la carpeta que contiene ambos archivos. Compare el digest con el valor que informa su SDK para ver con qué versión de la API se compiló el SDK.