2. Defining the public fields (1.x)

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 publicFieldsInfo which returns an array describing the fields you wish to make public.

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 publicFieldsInfo is defined in:

protected 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',
);

Available public field properties

The available properties depend on what class your resource inherits from. The basic properties, defined in the restfulBase class, are as follows:

• "process_callbacks": An array of callbacks to perform on the returned value, or an array with the object and method. Defaults To empty array.
• "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.
• "create_or_update_passthrough": Determines if a public field that isn't mapped to any property or field, may be passed upon create or update of an entity. Defaults to FALSE.

Entity-based resources

Entity-based resources, which extend the RestfulEntityBase class (either directly or via a parent class) have the following properties (defined in the class RestfulEntityBase, where you can find the following documentation):

• "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 access callback must return one of the following constants (as per Drupal's node access rules):

  • \RestfulInterface::ACCESS_ALLOW
  • \RestfulInterface::ACCESS_DENY
  • \RestfulInterface::ACCESS_IGNORE

  An example access_callback may be found here.

• "property": The entity property (e.g. "title", "nid").

• "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.

• "process_callbacks": An array of callbacks to perform on the returned value, or an array with the object and method. Defaults To empty array.

• "resource": This property can be assigned only to an entity reference field. Array of restful resources keyed by the target bundle. For example, if the field is referencing a node entity, with "Article" and "Page" bundles, we are able to map those bundles to their related resource. Items with bundles that were not explicitly set would be ignored. It is also possible to pass an array as the value, with:

  • "name": The resource name.
  • "full_view": Determines if the referenced resource should be rendered, or just the referenced ID(s) to appear. Defaults to TRUE.

  array(
    // Shorthand.
    'article' => 'articles',
    // Verbose
    'page' => array(
      'name' => 'pages',
      'full_view' => FALSE,
    ),
  );

• "create_or_update_passthrough": Determines if a public field that isn't mapped to any property or field, may be passed upon create or update of an entity. Defaults to FALSE.

  If TRUE, the public field is a dummy one, meant only for passing data upon create or update; it will not appear in read requests.

Examining a sample entity

With the Devel and Entity API modules turned on, you can use the following to find the fields available in a given entity on your site:

$node = node_load( 51242382 );
$node_wrapper = entity_metadata_wrapper('node', $node);
dpm($node_wrapper->getPropertyInfo());

...where 51242382 is the node id of your sample node.