Personnalisation des ressources

Certaines sites peuvent ne pas souhaiter exposer certains types de ressources JSON:API ou certains champs, ou bien vouloir renommer des champs pour offrir une interface plus claire.

Pour permettre ces modifications, JSON:API émet un objet événement ResourceTypeBuildEvent avec le nom d’événement ResourceTypeBuildEvents::BUILD. Veuillez consulter la page S’abonner et émettre des événements pour savoir comment utiliser ces événements.

Les abonnés peuvent appeler les méthodes suivantes :

• ResourceTypeBuildEvent::disableResourceType() pour empêcher qu’un type de ressource soit accessible de quelque manière que ce soit via JSON:API.
• ResourceTypeBuildEvent::disableField() pour empêcher qu’un champ soit accessible de quelque manière que ce soit via JSON:API.
• ResourceTypeBuildEvent::setPublicFieldName() pour définir un alias de champ afin que JSON:API n’expose pas le nom interne du champ Drupal.
• ResourceTypeBuildEvent::setResourceTypeName() pour définir un alias de ressource afin que JSON:API n’expose pas le nom interne de la ressource Drupal.

Tout module, personnalisé ou contribué, peut implémenter un abonné à cet événement. Cela signifie qu’un module spécifique à un site peut désactiver des types de ressources, et que les modules fournissant leurs propres types d’entités peuvent désactiver leurs propres représentations JSON:API.

Exemple

Voici un exemple de EventSubscriber qui montre toutes les actions possibles que vous pouvez effectuer.

<?php

namespace Drupal\modules\custom\resource_types\EventSubscriber;

use Drupal\jsonapi\ResourceType\ResourceTypeBuildEvents;
use Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

/**
 * Abonné à l'événement pour modifier certains types de ressources.
 */
class ResourceTypeBuildEventSubscriber implements EventSubscriberInterface {

  /**
   * {@inheritdoc}
   */
  public static function getSubscribedEvents() {
    return [
      ResourceTypeBuildEvents::BUILD => [
        ['disableResourceType'],
        ['aliasResourceTypeFields'],
        ['disableResourceTypeFields'],
        ['renameResourceType'],
      ],
    ];
  }

  /**
   * Désactive le type de ressource node/page.
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   L'événement de construction.
   */
  public function disableResourceType(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--page') {
      $event->disableResourceType();
    }
  }

  /**
   * Définit un alias "content" pour le champ body.
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   L'événement de construction.
   */
  public function aliasResourceTypeFields(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--article') {
      foreach ($event->getFields() as $field) {
        if ($field->getInternalName() === 'body') {
          $event->setPublicFieldName($field, 'content');
        }
      }
    }
  }

  /**
   * Désactive le champ sticky sur node--article.
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   L'événement de construction.
   */
  public function disableResourceTypeFields(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--article') {
      foreach ($event->getFields() as $field) {
        if ($field->getInternalName() === 'sticky') {
          $event->disableField($field);
        }
      }
    }
  }

  /**
   * Renomme node--article en article, exposant la ressource sous /jsonapi/article
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   L'événement de construction.
   */
  public function renameResourceType(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--article') {
      $event->setResourceTypeName('article');
    }
  }

}

JSON:API Extras

Certaines de ces fonctionnalités sont également fournies par JSON:API Extras. Ce module tente d’utiliser les fonctionnalités du noyau quand c’est possible, mais offre une interface et des fonctionnalités supplémentaires telles que :

1. Modifier le chemin de base de l’API.
2. Ajouter des améliorateurs aux champs.
3. Désactiver des ressources par défaut.

Après avoir activé le module, vous pouvez visiter /admin/config/services/jsonapi pour voir la liste de toutes les configurations et contenus exposés par JSON:API.

Article extrait de la documentation Drupal.