Drupal get a vocabulary list using REST API

For an introduction to setting up RESTful hal+json refer to the set-up documentation.  This article is about retrieving vocabulary lists that are used in many of the requests such as:

• Challenges:
  • Activate type {activate_time);
  • Distance marker {distance_marker};
  • Status {challenge_status}
• Notifications:
  • Audience {notification_audience};
  • Status {notification_status};
  • Type {notification_types}
• Rivals:
  • Status {notification_types}

The notation above is indicated as vocabulary name {vocabulary call}.  The vocabulary call is what will be used in the query string.  As an example to call the list for challenge status, use challenge_status.

Query string

The query string to get a vocabulary list is

{domain}/entity_rx/vocabulary/{name}?_format=hal_json

Replacing the following variables in the query string:

• {domain} ~ your-site.com
• {name} ~ challenge_status

Becomes:

your-site.com/entity_rx/vocabulary/challenge_status?_format=hal_json

Generates the following output:

{
    "9": "Cancelled",
    "3": "Creation",
    "6": "Finished",
    "5": "Live",
    "4": "Pending"
}

Whereas replacing {name} ~ notification_types

Becomes:

your-site.com/entity_rx/vocabulary/notification_types?_format=hal_json

Generates the following output:

{
    "21": {
        "10": "Accepted",
        "12": "Declined",
        "14": "Pending"
    },
    "20": {
        "11": "Comments"
    },
    "22": {
        "13": "Finished",
        "15": "Started"
    }
}

What is the code behind the above output?

The initial call in the plugin file is to a get function:

/*
   * Responds to GET requests.
   *
   * Returns a list of bundles for specified entity.
   *
   * @return \Drupal\rest\ResourceResponse
   *   The response containing a list of bundle names.
   *
   * @throws \Symfony\Component\HttpKernel\Exception\HttpException
   */
  public function get($vocab = NULL) {

    // reset the cache before beginning
    $cache = \Drupal::cache('dynamic_page_cache','data','rest');
    $cache->deleteAll();

    // limit the query to a user.uid.  If there is no uid, then return resource response empty
    if (empty($vocab)) {
      return new ResourceResponse(array());
    }
    // othrewise set the this->uid variable
    $this->vocabulary_name = $vocab;
    $this->getTaxonomy();

    if (!empty($this->taxonomy[$this->vocabulary_name])) {
      return new ResourceResponse($this->taxonomy[$this->vocabulary_name]);
    }

    return new ResourceResponse(array());
  }

Within this function there are calls to the getTaxonomy() function.

  /**
   * Load the taxonomy with a defined vocabulary name.
   *
   */
  protected function getTaxonomy() {
    if (!array_key_exists($this->vocabulary_name, $this->taxonomy)) {
      $query = \Drupal::entityQuery('taxonomy_term');
      $query->condition('vid', $this->vocabulary_name);
      $tids = $query->execute();
      $terms = \Drupal\taxonomy\Entity\Term::loadMultiple($tids);
      // get the terms
      foreach ($terms as $key => $term) {
        // notification category
        if ($this->vocabulary_name == 'notification_types') {
          $category = $term->field_notification_category->target_id;
          $this->taxonomy[$this->vocabulary_name][$category][$key] = $term->name->value;
        }
        else {
          $this->taxonomy[$this->vocabulary_name][$key] = $term->name->value;
        }
      }
    }

  }