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:
field_prefix.
Read even more examples on how to use the RESTful module in the module documentation node in Drupal.org. Make sure you read the Recipes section. If you have any to share, feel free to add your own recipes.
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[] = restfulregistry_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
http://example.com/api/v1.0/custom.
See the Defining a RESTful Plugin document for more details.
The following examples use the articles resource from the restful_example module.
// Get handler v1.1 $handler = restful()->getResourceManager()->getPlugin('articles:1.1');
$handler = restful() ->getResourceManager() ->getPlugin('articles:1.0'); // POST method, to create. $result = restful() ->getFormatterManager() ->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));
$handler = restful()->getResourceManager()->getPlugin('articles:1.0'); $handler->setRequest(Request::create('')); $result = restful()->getFormatterManager()->format($handler->process(), 'json');// Output: array( 'data' => array( array( 'id' => 1, 'label' => 'example title', 'self' => 'https://example.com/node/1', ); array( 'id' => 2, 'label' => 'another title', 'self' => 'https://example.com/node/2', ); ), );
See the Using your API within drupal documentation for more details.
The following examples use the articles resource from the restful_example module.
# Handler v1.0 curl https://example.com/api/articles/1 \ -H "X-API-Version: v1.0" # or curl https://example.com/api/v1.0/articles/1Handler v1.1
curl https://example.com/api/articles/1
-H "X-API-Version: v1.1"or
# Handler v1.1 curl https://example.com/api/articles/1,2 \ -H "X-API-Version: v1.1"
curl https://example.com/api/articles?autocomplete[string]=mystring
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:
admin/config/services/restfuland set CORS Preflight to the allowed domain. This will apply globally unless overridden with the method below.
allowOriginkey 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
allowOriginsettings, the top-level resource will be applied.
Clients can access documentation about a resource by making an
OPTIONSHTTP 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.
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
publicFieldswill output an object similar to the one listed above.
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.