Resource plugin definition properties

The plugin annotation may contain the following properties:

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

• dataProvider: 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.

  • idField: Some formatters, like JSON API, need to know how to identify a resource item. Since RESTful is not opinionated, you can use any field as the ID. It will be your responsibility to choose a field that contains unique values. Defaults to 'id'.

  Notable options for the entity based resources:

  • entityType: The entity type of the resource. Defaults to FALSE, which indicates the resource isn't connected to any entity type.
  • bundles: The name of bundles the resource is connected to. Defaults to FALSE.

  Notable properties for the database table based resources:

  • tableName: The name of the table to interact with.
  • idColumn: The tables id column.
  • primary: An string, or array of strings defining the primary field.

• majorVersion: 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.

• minorVersion: The minor version of the resource.

• options: Array of options needed for the plugin. Defaults to empty array.

• authenticationTypes: 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 UnauthorizedException exception would be thrown. Defaults to empty array, which means no authentication is done by default.

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

/**
 * Class CustomResource__1_0
 * @package Drupal\restful_custom\Plugin\resource
 *
 * @Resource(
 *   …
 *   authenticationTypes = TRUE,
 *   …
 * )
 */

• authenticationOptional: If "authenticationTypes" is TRUE, authenticationOptional determines if the resource may be accessed by an anonymous user when no provider was able to authenticate the user. Otherwise an UnauthorizedException exception would be thrown.
• hookMenu: Determines if RESTful module should declare the resource in its own hook_menu(). If FALSE, it is up to the implementing module to declare it. Defaults to TRUE.
• menuItem: Determines the URL where the resource is going to live. All paths specified using this definition property will be nested under the API's prefix. Ex: using menuItem: "my-resource" will result in https://example.org/api/my-resource.
• renderCache: 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.
  • simpleInvalidate: 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.
• rateLimit: 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.

public function __construct(…) {
  // …
  $plugin_definition = $this->getPluginDefinition();
  $plugin_definition['rateLimit'] = array(
    'request' => array(
      'event' => 'request',
      'period' => new \DateInterval('P1D'),
      'limits' => array(
        'authenticated user' => 100,
        'anonymous user' => 10,
        'administrator' => \Drupal\restful\RateLimit\RateLimitManager::UNLIMITED_RATE_LIMIT,
      ),
    ),
  );
  $this->setPluginDefinition($plugin_definition);
  // …
}

• 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 ID of the formatter plugin. It defaults to the contents of the variable 'restful_default_output_formatter'. If the variable is empty it defaults to 'json'. Recommended alternative is json_api.