Services
A standardized solution for integrating external applications with Drupal by providing a RESTful API framework with configurable endpoints, entity CRUD operations, and user authentication.
services
Overview
The Services module is a comprehensive API framework for Drupal that provides a standardized way to expose Drupal content and functionality to external applications. It extends beyond Drupal core's REST capabilities by offering a more flexible and feature-rich solution for building RESTful web services.
The module allows site administrators to create multiple service endpoints, each with its own URL prefix and configurable resources. Resources can be enabled or disabled per endpoint, and each resource can have its own authentication requirements and response format settings. This modular approach makes it easy to create different API versions or restrict access to specific functionality.
Built-in service definitions automatically provide CRUD operations (Create, Read, Update, Delete) for all Drupal entity types, including nodes, users, taxonomy terms, and custom entities. Additional service definitions provide user authentication (login/logout), taxonomy vocabulary tree retrieval, and node alias resolution. The module also supports Accept header-based content negotiation and includes CSRF token protection for secure API operations.
Features
- Create multiple API endpoints with custom URL prefixes for versioning or segmentation
- Automatic RESTful CRUD operations (GET, POST, PUT, DELETE) for all Drupal entity types
- Entity index endpoints with pagination support (start/limit parameters)
- Rendered entity view endpoint that returns HTML with associated CSS and JavaScript assets
- User authentication endpoints for login and logout with flood protection
- Taxonomy vocabulary tree retrieval for hierarchical term data
- Node retrieval by path alias for SEO-friendly URL support
- Accept header-based content negotiation (supports ?format=json query parameter)
- Configurable authentication providers per resource (cookie, basic_auth, oauth, etc.)
- Configurable response formats per resource (json, xml, hal_json, etc.)
- Per-resource caching control with option to disable response caching
- CSRF token endpoint for secure cross-site request protection
- HTTP middleware for format detection from Accept headers
- Plugin-based architecture allowing custom service definitions via ServiceDefinition annotation
Use Cases
Building a Headless Drupal Application
Use Services to expose all content as JSON APIs for a decoupled front-end built with React, Vue, or Angular. Create an endpoint at 'api/v1', enable entity resources for the content types you need, and configure cookie or OAuth authentication for protected operations.
Mobile Application Backend
Provide a REST API for iOS or Android applications. Enable entity_get and entity_index for reading content, user_login/user_logout for authentication, and entity_post/entity_put for user-generated content. Use JSON format with basic_auth or OAuth for secure mobile authentication.
Third-Party System Integration
Expose Drupal content to external systems like CRMs, ERPs, or other business applications. Create dedicated endpoints for each integration partner with specific resources and authentication requirements. Use the no_cache option for real-time data synchronization.
API Versioning Strategy
Create multiple endpoints like 'api/v1' and 'api/v2' to support different API versions simultaneously. Enable different resources or configure different formats per version to maintain backward compatibility while evolving your API.
Content Syndication
Allow partner sites to fetch and display your content. Create a public endpoint with entity_index and entity_get resources, configure JSON format, and use cookie authentication for anonymous access to published content only.
Tips
- Use the ?format=json query parameter as an alternative to Accept headers for easier testing in browsers and tools like curl
- Enable the RESTful Web Services UI (restui) module alongside Services for a visual interface to explore available resources
- For development, consider enabling all formats and authentication methods, then restrict for production
- Use the entity_view resource sparingly as it returns rendered HTML with assets, which may not be suitable for all API consumers
- Monitor flood protection settings in user.flood config if experiencing login issues during testing
- Create separate endpoints for public and authenticated resources to simplify security management
Technical Details
Admin Pages 6
/admin/structure/service_endpoint
Lists all configured service endpoints. From this page you can view, edit, delete endpoints and access their resource configurations. Each endpoint row shows the label, machine name, and provides operation links.
/admin/structure/service_endpoint/add
Create a new service endpoint that will serve as the base URL for your API. The endpoint path becomes the URL prefix for all resources enabled on this endpoint.
/admin/structure/service_endpoint/{service_endpoint}
Modify an existing service endpoint's label and URL path. The machine name cannot be changed after creation.
/admin/structure/service_endpoint/{service_endpoint}/resources
Configure which service definitions (resources) are enabled for this endpoint. Resources are grouped by category (entity type, User, Taxonomy, etc.). Each resource can be individually enabled/disabled and configured with specific authentication and format settings.
/admin/structure/service_endpoint/{service_endpoint}/resource/{plugin_id}
Configure authentication methods, response formats, and caching options for a specific resource on an endpoint.
/admin/structure/service_endpoint/settings
Configure global default settings that apply to all new resources. Individual resources can override these defaults.
Permissions 3
Hooks 2
hook_entity_form_display_access
Implements access control for entity form display operations via Services. Checks if the current user has the appropriate 'services {operation} form display access' permission.
hook_service_definition_info_alter
Allows modules to alter service definition plugin information. Called by the ServiceDefinitionPluginManager after discovering all plugins.
Troubleshooting 5
Obtain a CSRF token from /services/session/token and include it in the X-CSRF-Token header for all non-safe HTTP methods. The token is required even for authenticated requests.
Ensure the requested format is enabled for the resource. Check the Accept header matches a configured format, or use ?format=json query parameter. Verify the Serialization module is enabled.
Verify the authentication provider is enabled both globally in Drupal and for the specific resource. For cookie auth, ensure you're sending session cookies. For basic_auth, enable the Basic Auth module.
Check that the authenticated user has the required entity permissions (view, create, update, delete) in addition to any Services-specific permissions. Entity access is enforced at the Drupal level.
Clear the Drupal cache after modifying resource configurations. The routing system needs to rebuild to reflect changes. Use drush cr or clear cache via admin UI.
Security Notes 7
- Always use HTTPS in production to protect authentication credentials and API data in transit
- CSRF tokens are required for POST, PUT, and DELETE operations to prevent cross-site request forgery attacks
- Entity access permissions are enforced - users can only access/modify entities they have permission to
- Flood protection is implemented for login endpoints to prevent brute force attacks (configurable in user.flood)
- Consider using OAuth2 instead of cookie authentication for public APIs to improve security
- Review authentication provider settings carefully - leaving all providers enabled may expose sensitive operations
- The manage services permission grants full control over API configuration - assign carefully