Services
Una solución estandarizada para integrar aplicaciones externas con Drupal proporcionando un framework de API RESTful con endpoints configurables, operaciones CRUD de entidades y autenticación de usuarios.
services
Overview
El módulo Services es un framework de API integral para Drupal que proporciona una forma estandarizada de exponer el contenido y la funcionalidad de Drupal a aplicaciones externas. Extiende las capacidades REST del núcleo de Drupal ofreciendo una solución más flexible y rica en funcionalidades para construir servicios web RESTful.
El módulo permite a los administradores del sitio crear múltiples endpoints de servicio, cada uno con su propio prefijo de URL y recursos configurables. Los recursos pueden habilitarse o deshabilitarse por endpoint, y cada recurso puede tener sus propios requisitos de autenticación y configuración de formato de respuesta. Este enfoque modular facilita la creación de diferentes versiones de API o la restricción de acceso a funcionalidades específicas.
Las definiciones de servicio integradas proporcionan automáticamente operaciones CRUD (Crear, Leer, Actualizar, Eliminar) para todos los tipos de entidades de Drupal, incluyendo nodos, usuarios, términos de taxonomía y entidades personalizadas. Definiciones de servicio adicionales proporcionan autenticación de usuarios (inicio/cierre de sesión), recuperación del árbol de vocabularios de taxonomía y resolución de alias de nodos. El módulo también soporta negociación de contenido basada en cabeceras Accept e incluye protección con tokens CSRF para operaciones API seguras.
Features
- Crear múltiples endpoints de API con prefijos de URL personalizados para versionado o segmentación
- Operaciones CRUD RESTful automáticas (GET, POST, PUT, DELETE) para todos los tipos de entidades de Drupal
- Endpoints de índice de entidades con soporte de paginación (parámetros start/limit)
- Endpoint de vista de entidad renderizada que devuelve HTML con recursos CSS y JavaScript asociados
- Endpoints de autenticación de usuarios para inicio y cierre de sesión con protección contra flood
- Recuperación del árbol de vocabularios de taxonomía para datos de términos jerárquicos
- Recuperación de nodos por alias de ruta para soporte de URLs amigables para SEO
- Negociación de contenido basada en cabecera Accept (soporta parámetro de consulta ?format=json)
- Proveedores de autenticación configurables por recurso (cookie, basic_auth, oauth, etc.)
- Formatos de respuesta configurables por recurso (json, xml, hal_json, etc.)
- Control de caché por recurso con opción para deshabilitar el cacheo de respuestas
- Endpoint de token CSRF para protección segura contra solicitudes entre sitios
- Middleware HTTP para detección de formato desde cabeceras Accept
- Arquitectura basada en plugins que permite definiciones de servicio personalizadas mediante anotación ServiceDefinition
Use Cases
Construir una Aplicación Drupal Headless
Usa Services para exponer todo el contenido como APIs JSON para un front-end desacoplado construido con React, Vue o Angular. Crea un endpoint en 'api/v1', habilita recursos de entidad para los tipos de contenido que necesites, y configura autenticación por cookie u OAuth para operaciones protegidas.
Backend para Aplicación Móvil
Proporciona una API REST para aplicaciones iOS o Android. Habilita entity_get y entity_index para leer contenido, user_login/user_logout para autenticación, y entity_post/entity_put para contenido generado por usuarios. Usa formato JSON con basic_auth u OAuth para autenticación móvil segura.
Integración con Sistemas de Terceros
Expone contenido de Drupal a sistemas externos como CRMs, ERPs u otras aplicaciones empresariales. Crea endpoints dedicados para cada socio de integración con recursos específicos y requisitos de autenticación. Usa la opción no_cache para sincronización de datos en tiempo real.
Estrategia de Versionado de API
Crea múltiples endpoints como 'api/v1' y 'api/v2' para soportar diferentes versiones de API simultáneamente. Habilita diferentes recursos o configura diferentes formatos por versión para mantener compatibilidad hacia atrás mientras evolucionas tu API.
Sindicación de Contenido
Permite que sitios asociados obtengan y muestren tu contenido. Crea un endpoint público con recursos entity_index y entity_get, configura formato JSON, y usa autenticación por cookie para acceso anónimo solo a contenido publicado.
Tips
- Usa el parámetro de consulta ?format=json como alternativa a las cabeceras Accept para pruebas más fáciles en navegadores y herramientas como curl
- Habilita el módulo RESTful Web Services UI (restui) junto con Services para una interfaz visual para explorar recursos disponibles
- Para desarrollo, considera habilitar todos los formatos y métodos de autenticación, luego restringe para producción
- Usa el recurso entity_view con moderación ya que devuelve HTML renderizado con recursos, lo cual puede no ser adecuado para todos los consumidores de API
- Monitorea los ajustes de protección contra flood en la configuración user.flood si experimentas problemas de inicio de sesión durante pruebas
- Crea endpoints separados para recursos públicos y autenticados para simplificar la gestión de seguridad
Technical Details
Admin Pages 6
/admin/structure/service_endpoint
Lista todos los endpoints de servicio configurados. Desde esta página puedes ver, editar, eliminar endpoints y acceder a sus configuraciones de recursos. Cada fila de endpoint muestra la etiqueta, nombre de máquina y proporciona enlaces de operaciones.
/admin/structure/service_endpoint/add
Crea un nuevo endpoint de servicio que servirá como URL base para tu API. La ruta del endpoint se convierte en el prefijo de URL para todos los recursos habilitados en este endpoint.
/admin/structure/service_endpoint/{service_endpoint}
Modificar la etiqueta y ruta URL de un endpoint de servicio existente. El nombre de máquina no puede cambiarse después de la creación.
/admin/structure/service_endpoint/{service_endpoint}/resources
Configura qué definiciones de servicio (recursos) están habilitadas para este endpoint. Los recursos están agrupados por categoría (tipo de entidad, User, Taxonomy, etc.). Cada recurso puede habilitarse/deshabilitarse individualmente y configurarse con ajustes específicos de autenticación y formato.
/admin/structure/service_endpoint/{service_endpoint}/resource/{plugin_id}
Configura métodos de autenticación, formatos de respuesta y opciones de caché para un recurso específico en un endpoint.
/admin/structure/service_endpoint/settings
Configura los ajustes predeterminados globales que aplican a todos los nuevos recursos. Los recursos individuales pueden sobrescribir estos valores predeterminados.
Permissions 3
Hooks 2
hook_entity_form_display_access
Implementa control de acceso para operaciones de visualización de formularios de entidades a través de Services. Verifica si el usuario actual tiene el permiso apropiado 'services {operation} form display access'.
hook_service_definition_info_alter
Permite a los módulos alterar la información de plugins de definición de servicio. Llamado por ServiceDefinitionPluginManager después de descubrir todos los plugins.
Troubleshooting 5
Obtén un token CSRF desde /services/session/token e inclúyelo en la cabecera X-CSRF-Token para todos los métodos HTTP no seguros. El token es requerido incluso para solicitudes autenticadas.
Asegúrate de que el formato solicitado esté habilitado para el recurso. Verifica que la cabecera Accept coincida con un formato configurado, o usa el parámetro de consulta ?format=json. Verifica que el módulo Serialization esté habilitado.
Verifica que el proveedor de autenticación esté habilitado tanto globalmente en Drupal como para el recurso específico. Para autenticación por cookie, asegúrate de enviar las cookies de sesión. Para basic_auth, habilita el módulo Basic Auth.
Verifica que el usuario autenticado tenga los permisos de entidad requeridos (ver, crear, actualizar, eliminar) además de cualquier permiso específico de Services. El acceso a entidades se aplica a nivel de Drupal.
Limpia la caché de Drupal después de modificar configuraciones de recursos. El sistema de enrutamiento necesita reconstruirse para reflejar los cambios. Usa drush cr o limpia la caché mediante la UI de administración.
Security Notes 7
- Siempre usa HTTPS en producción para proteger credenciales de autenticación y datos de API en tránsito
- Los tokens CSRF son requeridos para operaciones POST, PUT y DELETE para prevenir ataques de falsificación de solicitudes entre sitios
- Los permisos de acceso a entidades se aplican - los usuarios solo pueden acceder/modificar entidades para las que tienen permiso
- La protección contra flood está implementada para endpoints de inicio de sesión para prevenir ataques de fuerza bruta (configurable en user.flood)
- Considera usar OAuth2 en lugar de autenticación por cookie para APIs públicas para mejorar la seguridad
- Revisa cuidadosamente los ajustes de proveedores de autenticación - dejar todos los proveedores habilitados puede exponer operaciones sensibles
- El permiso manage services otorga control total sobre la configuración de API - asigna con cuidado