Change record status: 
Project: 
Introduced in branch: 
8.2.x
Description: 

Until #2308745: Remove rest.settings.yml, use rest_resource config entities, all REST configuration lived inside a single rest.settings.yml file. Since that issue, only global settings (such as the link domain) still live in that file: the configuration for each REST resource now lives in a REST config entity. So one REST config entity per resource, for example node, user.

This was necessary because having a single (simple) configuration object for all configuration means that it's impossible to handle dependencies correctly: if the node module is uninstalled, we should also stop providing a node REST resource, but that was impossible to detect (because rest.settings cannot declare dependencies). Another example is that if an installation profile includes a custom rest.settings with configuration for custom REST resources in contrib modules, then it will fail because the contrib modules will not yet have been installed when rest.settings is being processed.

It also makes deploying new REST resources easier, because it's easier to get an overview of the different resources deployed: just look at the list of all REST resource config entities. Each of them lists its module dependencies.

Before

rest.settings

resources:
  entity:node:
    GET:
      supported_formats:
        - hal_json
      supported_auth:
        - basic_auth
    POST:
      supported_formats:
        - hal_json
      supported_auth:
        - basic_auth
    PATCH:
      supported_formats:
        - hal_json
      supported_auth:
        - basic_auth
    DELETE:
      supported_formats:
        - hal_json
      supported_auth:
        - basic_auth

After

rest.resource.entity.node

id: entity.node
plugin_id: 'entity:node'
granularity: method
configuration:
  GET:
    supported_formats:
      - hal_json
    supported_auth:
      - basic_auth
  POST:
    supported_formats:
      - hal_json
    supported_auth:
      - basic_auth
  PATCH:
    supported_formats:
      - hal_json
    supported_auth:
      - basic_auth
  DELETE:
    supported_formats:
      - hal_json
    supported_auth:
      - basic_auth
dependencies:
  module:
    - basic_auth
    - hal
    - node

There is an automatic update path provided.

Impacts: 
Site builders, administrators, editors
Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Module developer documentation done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other: 
Other updates done

Comments

dmouse’s picture

I used this code to migrate the old format


use Drupal\Core\Serialization\Yaml;

require __DIR__ . '/vendor/autoload.php';

$rest_settings = Yaml::decode(
  file_get_contents(__DIR__ . '/modules/my_own_rest/config/install/rest.settings.yml')
);

foreach ($rest_settings['resources'] as $id => $resource) {
  $rest = [];

  $rest_id = str_replace(':', '.', $id);

  $rest['id'] = $rest_id;
  $rest['plugin_id'] = $id;
  $rest['granularity'] = 'method';
  $rest['configuration'] = $resource;
  $rest['dependencies'] = [
    'module' => [
      'basic_auth',
    ]
  ];

  $yaml = Yaml::encode($rest);

  file_put_contents("rest.resource.$rest_id.yml", $yaml);
}