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 Management API uses this standard wherever paginated result sets are available — not just for assets and media, but across the whole API, including content generation sessions, teams, extensions and webhook listeners.

Connections

Connections are used to describe the connection between an object in the graph and the objects it is connected to. In the GraphQL Management API the viewer is connected to its mediaHubs and organizations, each media hub is connected to its assetRepositories, each asset repository is connected to its assetFolders and each asset folder is connected to its assets.

├── viewer
│   ├── mediaHubs
│   │   ├── assetRepositories
│   │   │   ├── assetFolders
│   │   │   │   ├── assets
│   ├── organizations

Edges and PageInfo

Connections will always contain edges and a pageInfo field (of type PageInfo).

The edge describes the relationship between the two nodes (e.g. between the media hub and the asset repository).

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 > node 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 Management API. Assets also have an assetId, which is a shorter UUID, which is for compatibility with 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:

• first specifies the number of results to return when paginating forwards, and is required whenever after is used
• last specifies the number of results when paginating backwards, and must be used together with before

The PageInfo object will allow you to determine whether there is a next or previous page (hasNextPage, hasPreviousPage) as well as the start and end cursor to use when paging (startCursor, endCursor).

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": [
        {
          "node": {
            "id": "QXNzZXQ6ZjQwYTQ2MjQtMDAyYS00YThiLTljODMtYzU4NDJmZWNhODkx",
            "name": "red-armchair"
          }
        },
        {
          "node": {
            "id": "QXNzZXQ6MDAxMTIyMzMtNDQ1NS02Njc3LTg4OTktYWFiYmNjZGRlZWZm",
            "name": "red-lamp"
          }
        }
      ]
    }
  }
}

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
      }
    }
  }
}

Note

assetSearch connections additionally return a total field with the overall result count, which is useful when building paging controls. total is specific to asset search results — most other connections in the API expose only edges and pageInfo.