Name: restful
Owner: RESTful-Drupal
Description: RESTful best practices for Drupal
Created: 2014-03-19 19:58:55.0
Updated: 2018-02-22 16:16:47.0
Pushed: 2017-12-14 10:25:57.0
Homepage: https://drupal.org/project/restful
Size: 2786
Language: PHP
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
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:
= RESTful custom
ription = Custom RESTful resource.
= 7.x
ndencies[] = restful
stry_autoload[] = PSR-4
space Drupal\restful_custom\Plugin\resource;
Drupal\restful\Plugin\resource\ResourceEntity;
Drupal\restful\Plugin\resource\ResourceInterface;
lass 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
s Custom__1_0 extends ResourceEntity implements ResourceInterface {
*
Overrides EntityNode::publicFields().
/
blic 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.
et handler v1.1
dler = restful()->getResourceManager()->getPlugin('articles:1.1');
dler = restful()
getResourceManager()
getPlugin('articles:1.0');
OST method, to create.
ult = restful()
getFormatterManager()
format($handler->doPost(array('label' => 'example title')));
= $result['id'];
ATCH method to update only the title.
uest['label'] = 'new title';
ful()
getFormatterManager()
format($handler->doPatch($id, $request));
dler = restful()->getResourceManager()->getPlugin('articles:1.0');
dler->setRequest(Request::create(''));
ult = restful()->getFormatterManager()->format($handler->process(), 'json');
utput:
y(
ata' => 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.
ndler v1.0
https://example.com/api/articles/1 \
"X-API-Version: v1.0"
https://example.com/api/v1.0/articles/1
ndler v1.1
https://example.com/api/articles/1 \
"X-API-Version: v1.1"
https://example.com/api/v1.1/articles/1
ndler v1.1
https://example.com/api/articles/1,2 \
"X-API-Version: v1.1"
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/restful
and set CORS Preflight to the
allowed domain. This will apply globally unless overridden with the method
below.allowOrigin
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 allowOrigin
settings, the
top-level resource will be applied.
Clients can access documentation about a resource by making an OPTIONS
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.
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:
yfield": {
"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 publicFields
will 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.