Importar tu API
Sube tu documento OpenAPI o tu colección de Postman, o indica su URL. Connect lee cada operación y convierte en tools las que puede usar.
En esta página
Formatos compatibles
| Formato | Versiones | Archivos |
|---|---|---|
| OpenAPI | 3.0 y 3.1 | JSON o YAML |
| Colección de Postman | 2.1 (también se acepta la 2.0) | JSON |
Swagger 2.0 y Postman 1.x no son compatibles. Conviértelos primero. El formato se detecta solo.
Archivo o URL
- Archivo:
.json,.yamlo.yml, hasta 5 MB. - URL: HTTPS y en el mismo dominio registrable que tu API verificada (por ejemplo
docs.acme.comparaapi.acme.com). Necesita el dominio verificado. Connect la descarga una vez, sin seguir redirecciones, en menos de 15 segundos.
Connect no guarda tu documento. Guarda una huella, su título y versión, los recuentos y la fecha.
Qué se convierte en tool
Nota
Por ahora, cada tool es una petición GET a tu API. Los demás métodos (POST, PUT, PATCH y DELETE) salen como omitidos.
Algunas operaciones GET también se omiten, con el motivo en el resultado:
| Motivo | Cuándo |
|---|---|
| Endpoint de inicio de sesión | Un segmento de la ruta o un nombre de operación como login, logout, signin, authenticate u oauth, o un parámetro que parece una contraseña o un token en la ruta. |
| Referencia externa | La operación o un parámetro obligatorio usa un $ref a otro archivo. Solo se siguen las referencias dentro del documento (#/...). |
| No válida | Una referencia que no se puede resolver, o una operación que Connect no puede leer. |
Algunos parámetros se descartan, con un aviso:
- Los parámetros de cabecera y de cookie. Las tools solo tienen parámetros de ruta y de query.
- Los parámetros que parecen credenciales, por ejemplo
api_keyotoken. - Los parámetros de ruta que no se usan en la ruta.
Las operaciones obsoletas (deprecated) se importan con un aviso.
Particularidades de Postman
- Los segmentos
:idy{{variable}}de la ruta se convierten en parámetros obligatorios. - Los parámetros de query son opcionales, con el tipo deducido del ejemplo. El valor de ejemplo nunca se guarda.
- Las cabeceras y la autenticación de Postman no se importan.
Nombres de las tools
Cada tool recibe un nombre como acme_list_orders: el slug como prefijo más el operationId (o la carpeta y el nombre de la petición en Postman), en minúsculas con guiones bajos, hasta 64 caracteres. Los nombres repetidos llevan _2, _3, etc. Puedes cambiar el nombre hasta que la tool se habilita por primera vez. Mira Tools.
Volver a importar
Puedes volver a importar cada vez que cambie tu API. Connect empareja cada operación con la tool que ya creó:
- OpenAPI: por
operationId, o por método y ruta si no lo tiene. - Postman: por el id de la petición, o por la ruta de carpetas y el nombre.
| La operación | Qué pasa con la tool |
|---|---|
| Es nueva | Se crea una tool nueva, sin canales y sin prueba. |
| No cambió | Nada. Se queda tal como la dejaste. |
| Cambió su ruta o sus parámetros | Toma la ruta y los parámetros nuevos, pierde la prueba y se deshabilita en todos los canales. Conserva su nombre, título, descripción, campos de respuesta y límite. |
| Desapareció | La tool se archiva y se deshabilita, solo si vuelves a importar la misma fuente (misma URL, mismo nombre de archivo o mismo título) y la importación trae al menos una tool. |
Si una importación no trae ninguna tool, no se archiva nada: deshabilita esas tools en sus canales a mano. Las tools archivadas vuelven si una importación posterior las trae otra vez. Tendrás que habilitarlas de nuevo en cada canal. Las tools que creas a mano nunca las toca una importación.
Límites
| Límite | Valor |
|---|---|
| Tamaño del documento | 5 MB |
| Tools por importación | 1.000 |
| Complejidad | 50.000 nodos |
| Importaciones por integración | 20 por hora |
Solo propietarios y administradores pueden importar. Se hace una importación a la vez por integración.