2. Defining the public fields (2.x)

On this page:

• Types of Fields and Properties
• Public field array keys
• Disabling a field
• Accepting data (POST and PUT requests)

RESTful defines several resource kinds through data providers, for example db table resources, entity resources and more.

Resources will usually want to provide public fields, which are the fields that the API makes available for requests to that endpoint.

Your resource plugin will need to implement the method publicFields which returns an array describing the fields you wish to make public.

Types of Fields and Properties

These fields are either Drupal fields, Drupal entity properties (such as nid, status, created etc) or completely arbitrary API fields that return anything you want. A simple example array for the latter would look like:

$public_fields['myField'] = array(
  'callback' => array($this, 'myFieldDataProviderCallbackWithALongName'),
);

which will call the specified function on the resource class your publicFields is defined in:

public function myFieldDataProviderCallbackWithALongName() {
  return 'barry';
}

A more typical case would be returning a field or property of the entity you're exposing on this resource. The following example exposes the author user ID:

$public_fields['uid'] = array(
  'property' => 'author',
  'sub_property' => 'uid',
);

Public field array keys

The publicFields method is originally defined in the class \Drupal\restful\Plugin\resource\Resource, and there you can find the following documentation about this array.

• "access_callbacks": An array of callbacks to determine if user has access to the property. Note that this callback is on top of the access provided by entity API, and is used for convenience, where for example write operation on a property should be denied only on certain request conditions. The Passed arguments are:

  • op: The operation that access should be checked for. Can be "view" or "edit".
  • public_field_name: The name of the public field.
  • property_wrapper: The wrapped property.
  • wrapper: The wrapped entity.

  The 'op' argument should return:

  • \Drupal\restful\Plugin\resource\Field\ResourceFieldBase::ACCESS_ALLOW,
  • \Drupal\restful\Plugin\resource\Field\ResourceFieldBase::ACCESS_DENY, or
  • \Drupal\restful\Plugin\resource\Field\ResourceFieldBase::ACCESS_IGNORE.

• "property": The entity property (e.g. "title", "nid"). Name of the property as described in hook_entity_property_info. Field API fields get this info by default, but you can declare your own.

• "sub_property": A sub property name of a property to take from it the content. This can be used for example on a text field with filtered text input format where we would need to do $wrapper->body->value->value(). Defaults to FALSE.

• "formatter": Used for rendering the value of a configurable field using Drupal field API's formatter. The value is the $display value that is passed to field_view_field().

• "wrapper_method": The wrapper's method name to perform on the field. This can be used for example to get the entity label, by setting the value to "label". Defaults to "value".

• "wrapper_method_on_entity": A Boolean to indicate on what to perform the wrapper method. If TRUE the method will perform on the entity (e.g. $wrapper->label()) and FALSE on the property or sub property (e.g. $wrapper->field_reference->label()). Defaults to FALSE.

• "column": If the property is a field, set the column that would be used in queries. For example, the default column for a text field would be "value". Defaults to the first column returned by field_info_field(), otherwise FALSE.

• "callback": A callable callback to get a computed value. The wrapped entity is passed as argument. Defaults To FALSE. The callback function receive as first argument the entity EntityMetadataWrapper object. CAUTION: Computed values do not provide free integration with sorts and filters.

• "process_callbacks": An array of callbacks to perform on the returned value, or an array with the object and method. Defaults to an empty array. When applying filters and sorts to any public field with process callbacks, the original unprocessed value will be considered.

• "resource": This property can be assigned only to an entity reference field. An array as the value, with:

  • "name": The resource name.
  • "fullView": Determines if the referenced resource should be rendered, or just the referenced ID(s) to appear. Defaults to TRUE.
  • "majorVersion": The major version of the resource to use.
  • "minorVersion": The minor version of the resource to use.

  array(
    'name' => 'pages',
    'fullView' => FALSE,
    'majorVersion' => 2,
    'minorVersion' => 1,
  );

• "methods": An array of HTTP methods allowed for this field. If a field is write only, set this to:

  'methods' => array(
    \Drupal\restful\Http\RequestInterface::METHOD_POST,
    \Drupal\restful\Http\RequestInterface::METHOD_PUT,
    \Drupal\restful\Http\RequestInterface::METHOD_PATCH,
  );

• "class": Each public field is mapped to a Field class. RESTful assigns a class to each field automatically if none is provided, based on the the field's type (e.g. entity reference, text, text-long, file, image etc). This is done in ResourceField::fieldClassName(). If you wish, you may specify each field's class explicitly inside publicFields(), e.g.

$public_fields['myNewField'] = array(
  'class' => '\Drupal\restful\Plugin\resource\Field\ResourceFieldKeyValue',
  // etc...
}

Disabling a field

If you want to disable a field without removing it –so it can be used programatically–. You can set the methods to an empty array.

Accepting data (POST and PUT requests)

Generally, data will be expected by RESTful (from POST and PUT requests) in the same format that it would be provided (in response to a GET request).

For example, the following public field definition:

      'description' => array(
        'property' => 'body',
        'sub_property' => 'value',
      ),

Would provide and expect that field's data in the following format:

{
  "description": "Some text",
}