Need help with restful?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

413 Stars 169 Forks 1.1K Commits 255 Opened issues


RESTful best practices for Drupal

Services available


Need anything else?

Contributors list

Build Status

RESTful best practices for Drupal

This module allows Drupal to be operated via RESTful HTTP requests, using best practices for security, performance, and usability.


Here are the differences between RESTful and other modules, such as RestWs and Services Entity:

  • RESTful requires explicitly declaring the exposed API. When enabling the module, nothing happens until a plugin declares it.
  • Resources are exposed by bundle, rather than by entity. This would allow a developer to expose only nodes of a certain type, for example.
  • The exposed properties need to be explicitly declared. This allows a clean output without Drupal's internal implementation leaking out. This means the consuming client doesn't need to know if an entity is a node or a term, nor will they be presented with the
  • Resource versioning is built-in, so that resources can be reused with multiple consumers. The versions are at the resource level, for more flexibility and control.
  • It has configurable output formats. It ships with JSON (the default one), JSON+HAL and as an example also XML.
  • Audience is developers and not site builders.
  • Provide a key tool for a headless Drupal. See the AngularJs form example module.

Module dependencies


Read even more examples on how to use the RESTful module in the module documentation node in Make sure you read the Recipes section. If you have any to share, feel free to add your own recipes.

Declaring a REST Endpoint

A RESTful endpoint is declared via a custom module that includes a plugin which describes the resource you want to make available. Here are the bare essentials from one of the multiple examples in the example module:


name = RESTful custom
description = Custom RESTful resource.
core = 7.x
dependencies[] = restful

registry_autoload[] = PSR-4


namespace Drupal\restful_custom\Plugin\resource;
use Drupal\restful\Plugin\resource\ResourceEntity;
use Drupal\restful\Plugin\resource\ResourceInterface;


  • Class Custom__1_0

  • @package Drupal\restful_custom\Plugin\resource

  • @Resource(

  • name = "custom:1.0",

  • resource = "custom",

  • label = "Custom",

  • description = "My custom resource!",

  • authenticationTypes = TRUE,

  • authenticationOptional = TRUE,

  • dataProvider = {

  • "entityType": "node",
  • "bundles": {
  •   "article"
  • },
  • },

  • majorVersion = 1,

  • minorVersion = 0

  • )

  • / class Custom__1_0 extends ResourceEntity implements ResourceInterface {


    • Overrides EntityNode::publicFields().

    • / public function publicFields() { $public_fields = parent::publicFields();

      $public_fields['body'] = array( 'property' => 'body', 'sub_property' => 'value', );

      return $public_fields; } }

After declaring this plugin, the resource could be accessed at its root URL, which would be

Security, caching, output, and customization

See the Defining a RESTful Plugin document for more details.

Using your API from within Drupal

The following examples use the articles resource from the restful_example module.

Getting a specific version of a RESTful handler for a resource

// Get handler v1.1
$handler = restful()->getResourceManager()->getPlugin('articles:1.1');

Create and update an entity

$handler = restful()
// POST method, to create.
$result = restful()
  ->format($handler->doPost(array('label' => 'example title')));
$id = $result['id'];

// PATCH method to update only the title. $request['label'] = 'new title'; restful() ->getFormatterManager() ->format($handler->doPatch($id, $request));

List entities

$handler = restful()->getResourceManager()->getPlugin('articles:1.0');
$result = restful()->getFormatterManager()->format($handler->process(), 'json');

// Output: array( 'data' => array( array( 'id' => 1, 'label' => 'example title', 'self' => '', ); array( 'id' => 2, 'label' => 'another title', 'self' => '', ); ), );

Sort, Filter, Range, and Sub Requests

See the Using your API within drupal documentation for more details.

Consuming your API

The following examples use the articles resource from the restful_example module.

Consuming specific versions of your API

# Handler v1.0
curl \
  -H "X-API-Version: v1.0"
# or

Handler v1.1

-H "X-API-Version: v1.1"



View multiple articles at once

# Handler v1.1
curl,2 \
  -H "X-API-Version: v1.1"

Returning autocomplete results


URL Query strings, HTTP headers, and HTTP requests

See the Consuming Your API document for more details.


RESTful provides support for preflight requests (see the Wikipedia example for more details).

To configure the allowed domains, you can:

  • Go to
    and set CORS Preflight to the allowed domain. This will apply globally unless overridden with the method below.
  • Set the
    key in your resource definition (in the annotation) to the allowed domain. This setting will only apply to this resource.

Bear in mind that this check is only performed to the top-level resource. If you are composing resources with competing

settings, the top-level resource will be applied.

Documenting your API

Clients can access documentation about a resource by making an

HTTP request to its root URL. The resource will respond with the field information in the body, and the information about the available output formats and the permitted HTTP methods will be contained in the headers.

Automatic documentation

If your resource is an entity, then it will be partially self-documented, without you needing to do anything else. This information is automatically derived from the Entity API and Field API.

Here is a snippet from a typical JSON response using only the automatic documentation:

  "myfield": {
    "info": {
      "label": "My Field",
      "description": "A field within my resource."
    "data": {
      "type": "string",
      "read_only": false,
      "cardinality": 1,
      "required": false
    "form_element": {
      "type": "textfield",
      "default_value": "",
      "placeholder": "",
      "size": 255,
      "allowed_values": null
  // { ... other fields would follow ... }

Each field you've defined in

will output an object similar to the one listed above.

Manual documentation

In addition to the automatic documentation provided to you out of the box, you have the ability to manually document your resources. See the Documenting your API documentation for more details.

Modules integration

  • Entity validator 2.x: Integrate with a robust entity validation (RESTful 1.x requires Entity Validator 1.x).


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.