1.1. Defining a resource plugin (1.x)

See "Defining our RESTful Plugin" on http://www.edhollinghurst.com/blog/getting-started-with-restful.html for a tutorial covering the basics.

NOTE: if you need your endpoint to be protected by authentication, you must specify the authentication_types key. Either specify an array of auth types, or TRUE for any.

$plugin = array(
  // ...
  // Try to authenticate users with all available authentication types.
  'authentication_types' => TRUE,
);

Plugin definition properties

The $plugin array may contain the following properties (taken from restful/includes/RestfulManager.php):

• description: The description of the resource. Defaults to empty string.
• discoverable: Determines if the resource should be discoverable by the "discovery" resource. Defaults to TRUE.
• data_provider_options: An array of options specific to the data provider. For example the DB query data provider requires the table name in order to know which table to act upon. Defaults to an empty array.
• major_version: The major version of the resource. This will change the URL of the resource endpoint. For example setting major version to 2 for the "articles" resource will result with "api/v2/articles" as the URL. Defaults to 1.
• minor_version: The minor version of the resource. Setting the minor version via CURL is done by setting HTTP_X_RESTFUL_MINOR_VERSION in the HTTP headers. Defaults to 0.
• options: Array of options needed for the plugin. See "per_role_content__1_0.inc" in RESTful example module. Defaults to empty array.
• entity type: The entity type of the resource. Defaults to FALSE, which indicates the resource isn't connected to any entity type.
• bundle: The name of a single bundle the resource is connected to. Defaults to FALSE.
• authentication_types: TRUE or Array with name of authentication providers that should "protect" the resource, and ensure only authenticated users can use it. If set to TRUE, then all the existing authentication providers would be used until the user is authenticated. If user was not authenticated with any of the authentication providers, an \RestfulUnauthorizedException exception would be thrown. Defaults to empty array, which means no authentication is done by default.
• authentication_optional: If "authentication_types" and TRUE this determines if the resource may be accessed by an anonymous user when no provider was able to authenticate the user. Otherwise a \RestfulUnauthorizedException exception would be thrown.
• hook_menu: Determines if RESTful module should declare the resource in its pwn hook_menu(). If FALSE, it is up to the implementing module to declare it. Defaults to TRUE.
• render_cache: Stores the cache settings. An associative array with:
  • render: Set it to FALSE to disable the render cache completely Defaults to FALSE.
  • class: The cache class for this resource. Defaults to NULL, which will probably end up resolving to 'DrupalDatabaseCache'.
  • bin: The name of the bin. It is the developer's responsibility to create this bin in the cache backend if it does not exist. Defaults to 'cache_restful'.
  • expire: TTL for the cache records. See DrupalCacheInterface::set() for the allowed values. Defaults to CACHE_PERMANENT.
  • simple_invalidate: Set it to false to prevent the RESTful module to invalidate any cache it may have been generated. The developer will be responsible to invalidate caches in this scenario. Defaults to TRUE.
  • granularity: DRUPAL_CACHE_PER_USER or DRUPAL_CACHE_PER_ROLE.
• rate_limit: The configuration array for the rate limits. There is a special limit category called 'global' that will not be limited to resource but will aggregate all request hits across all resources. To enable the global limit set the variable 'restful_global_rate_limit' to the desired limit and 'restful_global_rate_period' to the wanted period.
  • period: A \DateInterval object representing the period on which the rate limitations apply.
  • event: The name of the event to limit as declared in the rate_limit plugin.
  • limits: An associative array with the number of allowed requests in the selected period for every role.

    array(
      'request' => array(
        'event' => 'request',
        'period' => new \DateInterval('P1D'),
        'limits' => array(
          'authenticated user' => 100,
          'anonymous user' => 10,
          'administrator' => \RestfulRateLimitManager::UNLIMITED_RATE_LIMIT,
        ),
      ),
    ),

• autocomplete: Stores the autocomplete settings. An associative array with:
  • enable: Determines if the autocomplete functionality should be used. Defaults to TRUE.
  • range: Determines how many matches should return on every query. Defaults to 10.
  • operator: Determines the operator used to match the given string. Values can be 'STARTS_WITH' or 'CONTAINS'. Defaults to 'CONTAINS'.
• formatter: The name of the formatter plugin. It defaults to the contents of the variable 'restful_default_output_formatter'. If the variable is empty it defaults to 'hal_json'.
• url_params: Associative array to configure if the "sort", "filter" and "range" url parameters should be allowed. Defaults to TRUE in all of them.
• view_mode: Associative array that contains two keys:
  • name: The name of the view mode to read from to add the public fields.
  • field_map: An associative array that pairs the name of the Drupal field with the name of the exposed (public) field.