La API de Kontainer facilita integrar tu software actual en la plataforma de Kontainer. Esta interfaz entre programas permite que tus aplicaciones intercambien datos con Kontainer y se puede usar para automatizar muchos procesos distintos.
A continuación repasamos los fundamentos de la configuración de la API.
La información de este artículo es técnica y está dirigida a los desarrolladores encargados de configurar la API. Si tienes cualquier duda, no dudes en escribirnos.
Visita la página de integración de Kontainer para saber más sobre nuestra API. Encontrarás más información sobre casos de uso, ventajas, etc.
Código de la API
Ve directamente al código para la integración con la API AQUÍ (en inglés).
NOTA: debes usar tu URL de Kontainer única en lugar de la que aparece en el ejemplo de los enlaces anteriores («app.kontainer.com»).
Primeros pasos
Para usar la API de Kontainer necesitas una cuenta de Kontainer y un token de acceso a la API.
Ponte en contacto con tu administrador local o con el soporte de Kontainer para obtener más información sobre cómo acceder a la API de Kontainer.
Autenticación
La API de Kontainer usa OAuth para la autenticación. Cuando te den un token de acceso a la API, debes enviarlo en cada solicitud, en la cabecera Authorization, como valor «Bearer».
Todas las solicitudes deben incluir tu token de acceso a la API en la cabecera Authorization: Authorization: Bearer {{access-token}}
Negociación de contenido
Todas las solicitudes deben incluir la cabecera: Accept: application/vnd.api+json .
Las solicitudes que envíen datos JSON deben incluir la cabecera: Content-Type: application/vnd.api+json
Estándar JSON:API
La API de Kontainer es una API RESTful que sigue el estándar JSON API. Puedes consultar este estándar para más información sobre cómo se estructuran los documentos de solicitud y de respuesta.
Tipos de recurso
La API expone estos tipos de recurso: files, folders, users, tags, channels, elements, element-options, categories, custom-fields, download-templates, video-download-templates, cdn, user-groups, permisos de carpetas (folder permissions), consent wards, consent agreements, consent parties, statistics y registros de tareas (job logs).
Operaciones de escritura
La API admite operaciones de escritura en todos los recursos: POST para crear, PATCH para actualizar y DELETE para eliminar. No es de solo lectura.
Límites de frecuencia
Los límites de frecuencia estándar de la API se aplican a todos los endpoints que ofrecemos, y el límite es de 500 solicitudes por minuto. Si se supera el límite definido, la API responde con el mensaje: 429: Too Many Attempts.
Códigos de respuesta
La API de Kontainer responde con códigos de estado HTTP y con códigos y mensajes de error basados en JSON.
Códigos de estado HTTP
La tabla siguiente ofrece un resumen de los códigos de estado HTTP que se devuelven.
| Código de estado HTTP | Texto | Descripción |
|---|---|---|
| 200 | OK | Correcto. |
| 201 | Created | Objeto creado. |
| 204 | No Content | No se devuelve contenido. |
| 401 | Unauthorized | Falta el token o no es válido. |
| 403 | Forbidden | Recurso o solicitud no admitidos. |
| 404 | Not Found | Objeto no encontrado. |
| 406 | Not Acceptable | Solicitud no aceptable. |
| 409 | Conflict | Conflicto con el estado de la aplicación o del recurso. |
| 422 | Validation Error | Se ha producido un error de validación. |
| 429 | Too Many Requests | Se ha superado el límite de frecuencia. |
Mensajes de error
El ejemplo siguiente muestra el aspecto que tiene un mensaje de error para el código de estado HTTP 401 - Unauthorized.
Filtros
Se pueden aplicar filtros a los endpoints compatibles para limitar los resultados que se devuelven. Los filtros se aplican con el parámetro de consulta filter. Los campos de filtro admitidos aparecen en la sección Filter Attributes de cada endpoint.
Ejemplos:
Obtener una lista de elementos o productos de una categoría:
filter[description][like] : Shoes
Encontrar elementos por EAN exacto:
filter[ean][eq] : 4194382028137
Encontrar elementos posteriores a una fecha:
filter[released_on][gt] : 2020-01-01
Encontrar elementos con un coste unitario mayor o igual que 22,50 y menor que 50,00:
filter[unit_cost][gte] : 22.50
filter[unit_cost][lt] : 50.00
Comprobar si hay archivos a los que se hace referencia en un campo de datos del PIM:
filter[asset][exists] : 1
filter[asset][exists] : 0
Calificadores de filtro
- Igual a: [eq]
- En: [in]
- Similar a: [like]
- Mayor que: [gt]
- Mayor o igual que: [gte]
- Menor que: [lt]
- Menor o igual que: [lte]
- No en: [notin]
- Distinto de: [ne] (ten en cuenta: solo PIM)
- Existe: [exists] (ten en cuenta: solo PIM)
Nota: los calificadores de filtro permitidos dependen del elemento en el que se busca.
Documentos compuestos
JSONAPI - Compound Documents (en inglés)
Para reducir el número de solicitudes HTTP, en los endpoints compatibles se puede pedir que las respuestas «incluyan» (include) los recursos relacionados junto con los recursos principales solicitados. Los recursos incluidos se piden con el parámetro de consulta include. Los elementos incluibles admitidos aparecen en la sección Available Includes de cada endpoint.
Ejemplos:
- En el endpoint GET /elements, para incluir las opciones de elemento asociadas:
include: element_option - En el endpoint GET /items, para incluir los elementos raíz, principal y secundarios:
include: parent_item,root_item,children
Paginación
Las respuestas están paginadas, con un tamaño de página configurable. No se ofrecen endpoints masivos ni webhooks.
Código de la API
Ve directamente al código para la integración con la API AQUÍ (en inglés).
NOTA: debes usar tu URL de Kontainer única en lugar de la que aparece en el ejemplo de los enlaces anteriores («app.kontainer.com»).