Version Retrieval

Retrieve a Version by Work ID and Version Label

Retrieve a specific version of a work by label with optional includes and release guards. Response schemas are the same returned by the API endpoints described here.

const res = await client.works.getVersionByLabel(
    "work-id-123", // required; Dryad work identifier
    "v1", // required; version label to retrieve
    {
      include: ["assets"], // optional; string or string[] of related resources
      doi: "10.1234/example.v1", // optional; filter by DOI for safety
      releasedAfter: "2024-01-01", // optional; ISO8601 lower bound on release date
      releasedBefore: "2024-12-31", // optional; ISO8601 upper bound on release date
    }
  );

Retrieve all Versions of a Work

Page through all versions of a work with sorting, filtering, and include options. Response schemas are the same returned by the API endpoints described here.

const res = await client.works.listVersions(
    "work-id-123", // required; Dryad work identifier
    {
      limit: 20, // optional; max versions per page
      cursor: "opaque-cursor", // optional; pagination cursor from previous response
      sort: "releasedAt", // optional; sort field ("releasedAt"|"id")
      order: "desc", // optional; sort direction ("asc"|"desc")
      include: ["assets"], // optional; string or string[] of related resources
      versionLabel: "v1", // optional; restrict to a specific label
      doi: "10.1234/example.v1", // optional; filter by DOI
      releasedAfter: "2024-01-01", // optional; ISO8601 lower bound on release date
      releasedBefore: "2024-12-31", // optional; ISO8601 upper bound on release date
    }
  );

Retrieve a Version by Version ID

Similarly to using client.works.getVersionByLabel , you can retrieve a version by its version ID using client.versions.get . A Version ID can be constructed as {Work ID}.{Version Label}.

const version = await client.versions.get(
    "version-123", // required; unique version identifier returned by the API
    {
      expand: ["sections", "blocks", "assets", "citations", "metadata"], // optional; request additional embedded datasets (or use "all")
    }
  );

To avoid the use of expand like above, and to make the code cleaner, you can perform targetted data retrievals using the following methods:

  const versionWithAll = await client.versions.getWithAllExpansions(
    "version-123" // required; unique version identifier
  );

  const sections = await client.versions.getSections(
    "version-123" // required; unique version identifier
  );

  const blocks = await client.versions.getBlocks(
    "version-123" // required; unique version identifier
  );

  const assets = await client.versions.getAssets(
    "version-123" // required; unique version identifier
  );

  const citations = await client.versions.getCitations(
    "version-123" // required; unique version identifier
  );