JSON:API backend
La API JsonDrop utiliza la implementación JSON:API para la interacción backend/frontend y es una implementación totalmente compatible con la:
Colección Postman con endpoints listos para usar:
https://drive.google.com/file/d/1rMf0XdrK1zXwPqLQVsTH44Z2ttFxj7ss/view?usp=drive_link
En sus propias palabras, la especificación JSON:API es:
[Una] especificación sobre cómo un cliente debe solicitar que los recursos sean obtenidos o modificados, y cómo un servidor debe responder a esas solicitudes.
JSON:API está diseñado para minimizar tanto el número de solicitudes como la cantidad de datos transmitidos entre clientes y servidores. Esta eficiencia se logra sin comprometer la legibilidad, flexibilidad ni la capacidad de descubrimiento.
Las estructuras de datos de Drupal, es decir, tipos de entidad, bundles y campos, son increíblemente adecuadas para JSON:API.
Al habilitar el módulo JSON:API, obtienes inmediatamente una API REST completa para cada tipo en tu aplicación Drupal. JSON:API inspecciona tus tipos de entidad y bundles para proporcionar dinámicamente URLs mediante las cuales acceder a cada uno de ellos usando los métodos HTTP estándar: GET, POST, PATCH y DELETE.
JSON:API adopta la filosofía de que el módulo debe estar listo para producción "desde el primer momento". Esto significa que el módulo tiene una opinión clara sobre dónde residirán tus recursos, qué métodos están disponibles inmediatamente en ellos, y deja el control de acceso al sistema de permisos del núcleo de Drupal. Actualmente, no existen páginas de configuración disponibles. Esto significa que puedes iniciar rápidamente una aplicación Drupal basada en API con un esfuerzo mínimo.
Las páginas hijas de esta documentación incluirán:
- Conceptos básicos de la especificación JSON:API y cómo se aplican en Drupal
- Una visión general amplia de la API que el módulo pone a disposición
- Información práctica sobre cómo crear tus solicitudes HTTP
- Cómo autenticar tus solicitudes
- Errores comunes ("gotchas")
- Documentación específica para:
- Obtención de recursos individuales (GET)
- Obtención de colecciones de recursos (GET con filtros, paginación y ordenación)
- Creación de nuevos recursos (POST)
- Actualización de recursos existentes (PATCH)
- Eliminación de recursos existentes (DELETE)
Si tienes preguntas específicas, crea una solicitud de soporte en la cola de incidencias del módulo JSON:API [480 issues].
La API que el módulo JSON:API pone a disposición está centrada en los tipos de entidad y bundles de Drupal. Cada bundle recibe su propia URL única, que sigue un patrón común.
A diferencia del módulo REST del núcleo de Drupal, estas rutas no son configurables y están todas habilitadas por defecto. JSON:API no es simplemente un formato como JSON o HAL+JSON. Abarca un conjunto mucho más amplio de reglas sobre cómo funcionará tu API. Dicta qué métodos HTTP deben usarse, qué códigos de respuesta HTTP deben devolverse en circunstancias específicas, el formato del cuerpo de respuesta, y la vinculación entre recursos. Para una comparación más detallada, consulta JSON:API vs. el módulo REST del núcleo.
Tipos
Cada recurso en JSON:API debe tener una propiedad type globalmente única. La implementación JSON:API de Drupal deriva esta propiedad de tipo a partir del nombre máquina del tipo de entidad y del bundle. Por ejemplo, artículos, páginas y usuarios reciben los tipos node--article, node--pages y user--user respectivamente. Nota que el tipo de entidad usuario en Drupal no tiene bundles. Cuando un tipo de entidad no tiene bundle, el tipo de entidad se repite para mantener la consistencia.
Estructura de la URL
Una URL JSON:API se ve así:
GET|POST /jsonapi/node/article
PATCH|DELETE /jsonapi/node/article/{uuid}
Cada tipo de recurso debe ser direccionable de forma única en la API. Esto significa que cada tipo disponible para la API debe tener una URL única. Además, sólo un tipo de recurso puede ser obtenido por una URL dada. La implementación de Drupal sigue el patrón: /jsonapi/{entity_type_id}/{bundle_id}[/{entity_uuid}].
La URL siempre está prefijada por /jsonapi.
Después, el id del tipo de entidad y el id del bundle se concatenan con una barra diagonal. Nota que no existe una URL en /jsonapi/node, porque esa URL violaría la especificación al servir múltiples tipos de recursos (por múltiples bundles) desde una única URL.
Existen:
/jsonapi/node/page
/jsonapi/node/article
No existen:
/jsonapi/node
Tras el tipo de entidad y el bundle, hay una parte opcional de ID. Para direccionar un recurso único, ya sea para obtenerlo, actualizarlo o eliminarlo, debes incluir esta parte en la ruta. Siempre es el UUID del recurso. Al crear un recurso nuevo, o al obtener una colección de recursos de un solo tipo, se omite esta parte.
GET, POST
/jsonapi/node/article
PATCH, DELETE
/jsonapi/node/article/{uuid}
Métodos HTTP
JSON:API especifica qué métodos HTTP aceptar: GET, POST, PATCH y DELETE. Notablemente, PUT no está incluido.
- GET - Recuperar datos, puede ser una colección o un recurso individual
- POST - Crear un recurso nuevo
- PATCH - Actualizar un recurso existente
- DELETE - Eliminar un recurso existente
Encabezados de solicitud
Asegúrate de usar los encabezados 'Content-Type' y 'Accept' cuando sea apropiado. Consulta Responsabilidades del cliente para más detalles.
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Códigos de respuesta
La especificación JSON:API también dicta respuestas aceptables. La implementación de Drupal usa un subconjunto de ellas. El módulo puede responder con los siguientes códigos:
- 200 OK - Para todas las solicitudes GET y PATCH exitosas
- 201 Created - Para todas las solicitudes POST exitosas (la respuesta incluye el recurso recién creado)
- 204 No Content - Para todas las solicitudes DELETE exitosas
Artículo extraído de Documentación de Drupal.