annotate core/modules/jsonapi/src/Revisions/VersionNegotiatorInterface.php @ 19:fa3358dc1485 tip

Add ndrum files
author Chris Cannam
date Wed, 28 Aug 2019 13:14:47 +0100
parents af1871eacc83
children
rev   line source
Chris@18 1 <?php
Chris@18 2
Chris@18 3 namespace Drupal\jsonapi\Revisions;
Chris@18 4
Chris@18 5 use Drupal\Core\Entity\EntityInterface;
Chris@18 6
Chris@18 7 /**
Chris@18 8 * Defines the common interface for all version negotiators.
Chris@18 9 *
Chris@18 10 * @internal JSON:API maintains no PHP API since its API is the HTTP API. This
Chris@18 11 * class may change at any time and this will break any dependencies on it.
Chris@18 12 *
Chris@18 13 * @see https://www.drupal.org/project/jsonapi/issues/3032787
Chris@18 14 * @see jsonapi.api.php
Chris@18 15 *
Chris@18 16 * @see \Drupal\jsonapi\Revisions\VersionNegotiator
Chris@18 17 */
Chris@18 18 interface VersionNegotiatorInterface {
Chris@18 19
Chris@18 20 /**
Chris@18 21 * Gets the identified revision.
Chris@18 22 *
Chris@18 23 * The JSON:API module exposes revisions in terms of RFC5829. As such, the
Chris@18 24 * public API always refers to "versions" and "working copies" instead of
Chris@18 25 * "revisions". There are multiple ways to request a specific revision. For
Chris@18 26 * example, one might like to load a particular revision by its ID. On the
Chris@18 27 * other hand, it may be useful if an HTTP consumer is able to always request
Chris@18 28 * the "latest version" regardless of its ID. It is possible to imagine other
Chris@18 29 * scenarios as well, like fetching a revision based on a date or time.
Chris@18 30 *
Chris@18 31 * Each version negotiator provides one of these strategies and is able to map
Chris@18 32 * a version argument to an existing revision.
Chris@18 33 *
Chris@18 34 * @param \Drupal\Core\Entity\EntityInterface $entity
Chris@18 35 * The entity for which a revision should be resolved.
Chris@18 36 * @param string $version_argument
Chris@18 37 * A value used to derive a revision for the given entity.
Chris@18 38 *
Chris@18 39 * @return \Drupal\Core\Entity\EntityInterface
Chris@18 40 * The identified entity revision.
Chris@18 41 *
Chris@18 42 * @throws \Drupal\jsonapi\Revisions\VersionNotFoundException
Chris@18 43 * When the revision does not exist.
Chris@18 44 * @throws \Drupal\jsonapi\Revisions\InvalidVersionIdentifierException
Chris@18 45 * When the revision ID is invalid.
Chris@18 46 */
Chris@18 47 public function getRevision(EntityInterface $entity, $version_argument);
Chris@18 48
Chris@18 49 }