Conventions

Connections and pagination

GraphQL Cursor Connections Specification, or Relay spec provides a consistent interface for querying by id and for pagination within queries that return a list.

The GraphQL Asset Management API uses this standard wherever paginated results sets are available.

Connections

Connections are used to describe the connection between an object in the graph and the objects it is connected to. In the Asset Management API the viewer is connected to mediaHubs and organisations, each mediaHub is connected to its assetRepositories, each assetRepository is connected to its assetFolders and each assetFolder is connected to its assets.

├── viewer
│   ├── mediaHub
│   │   ├── assetRepository
│   │   │   ├── assetFolders
│   │   │   │   ├── assets
│   ├── organisations

Edges and PageInfo

Connections will always contain edges and a PageInfo object.

The edge describes the relationship between the two nodes (e.g. between the mediaHub and the assetRepository).

The PageInfo object describes the current set of results and is detailed in the Pagination section below.

Nodes

A node is a single entity in the graph, for example an asset or an assetFolder.

Single node queries

You can fetch a single asset using the node query

{
  node(id: "QXNzZXQ6ZjQwYTQ2MjQtMDAyYS00YThiLTljODMtYzU4NDJmZWNhODkx") {
    id
    ... on Asset {
      mimeType
    }
  }
}

Multiple node queries

Queries that return a list (multiple nodes) use the connection > edges > nodes structure defined by the Cursor Connections Specification.

For example to return the list of assets for an assetSearch query:

{
  assetSearch(keyword: "Red") {
    edges {
      node {
        id
        name
      }
    }
  }
}

note

The id used in node queries is a specific id for use within our GraphQL Asset Management API. Assets also have an assetId, which is a shorter UUID, which is for compatibility with Dynamic assets, asset manifests and existing integrations.

Pagination

For multiple node queries that support pagination, the values in the pageInfo object can be used along with the arguments first and after or last and before.

The PageInfo object will allow you to determine whether there is a next or previous page as well as the start and end cursor to use when paging.

For example the following assetSearch query

{
  assetSearch(keyword: "Red") {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}

Returns this response:

{
  "data": {
    "assetSearch": {
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "eyJtYXJrZXIiOiJBb0lJUDRBQUFEOEZabVpo..."
      },
      "edges": []
    }
  }
}

The endCursor value from the response can then be passed into the after argument of the next request:

{
  assetSearch(
    keyword: "Red"
    first: 20
    after: "eyJtYXJrZXIiOiJBb0lJUDRBQUFEOEZabVpo..."
  ) {
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        id
        name
      }
    }
  }
}