REST to GraphQL#

This guide documents how to transform the REST calls to GraphQL queries and provides some examples.

Exclude and Include REST query parameters#

REST endpoints use exclude and include parameters to exclude or include specific fields in the response.

Exclude#

In REST this parameter takes a comma separated list of fields to exclude in the response. You can use dot notation to define nested fields.

In GraphQL, this is done implicitly by simply not including the field in the query.

Include#

In REST this parameter takes a comma separated list of fields to include in the response. You can use dot notation to define nested fields. If not specified, REST returns the entire object.

This mimics the GraphQL behavior, where you have to explicitly include the fields you want in the response.

Note: To take advantage of the Field selection mechanism in REST you need to use these parameters. It is better to use GraphQL. This will limit the amount of data returned by the API and improve performance.

GraphQL query:

{
  find_images {
    error {
      status
      detail
    }
    data {
      _id
    }
  }
}

REST endpoint call equivalent:

https://catalog.redhat.com/api/containers/v1/images?include=data._id

This query will return only the _id field of images.

Note: When returning more objects in REST, you need to use data before all fields, for example data._id. When returning only one object, you can use _id directly.

Path and Query Parameters#

REST endpoints use path and query parameters. Both of these parameters are represented as GraphQL arguments.

GraphQL query:

{
  find_repository_images_by_registry_path(registry: "example_registry", repository: "example_repository", page: 0, page_size: 50) {
    error {
      detail
      status
    }
    data {
      _id
    }
  }
}

REST enpoint call equivalent:

https://catalog.redhat.com/api/containers/v1/repositories/registry/example_registry/repository/example_repository/images?page=0&page_size=50&include=data._id

In this example:

- The path parameters are example_registry and example_repository
- The query parameters are after `?` which are page=0 and page_size=50 and include=data._id

Sort_by and Filter#

Other notable query parameters used in REST are sort_by and filter. In GraphQL they are once again represented as query arguments.

GraphQL query using sort_by:

{
  find_images(sort_by: [{ field: "creation_date", order: DESC }, {field: "last_update_date", order: ASC}]) {
    error {
      detail
      status
    }
    data {
      _id
    }
  }
}

REST endpoint call equivalent using sort_by:

https://catalog.redhat.com/api/containers/v1/images?sort_by=creation_date[desc],last_update_date[asc]&include=data._id

This query will sort the images in such a way that the newest items come first, and items with the same creation date will be also sorted based on last_update_date field in ascending order. Which means that images with earlier last update dates come first.

Note: Priority of ordering is determined by order of fields set in sort_by list.

GraphQL query using filter:

{
  find_repositories(
    filter: {
      and: [
        organization: {
          eq: "example_organization"
        }
        latest_in_channel: {
          ne: true
        }
      ]
    }
  ) {
    error {
      status
      detail
    }
    data {
      _id
    }
  }
}

REST endpoint call equivalent using filter:

https://catalog.redhat.com/api/containers/v1/operators/bundles?filter=organization=="example_organization" and latest_in_channel!=true&include=data._id

For more information about filtering in GraphQL you can look up the Advanced filtering section in documentation.

Other frequent query examples#

GraphQL query update:

{
  update_image(
    id: "abc123"
    input: {
      freshness_grades: [
        {
          creation_date: "2023-08-04T15:37:13.036743+00:00", 
          grade: "A", 
          start_date: "2023-08-04T15:37:13.036743+00:00"
        }
      ]
    }
  ) {
    error {
      status
      detail
    }
    data {
      _id
    }
  }
}

REST call endpoint equivalent patch object:

curl -X 'PATCH' \
  'https://catalog.redhat.com/api/containers/v1/images/id/abc123' \
  -d '{
    "freshness_grades": [
          {
            "creation_date": "2023-08-04T15:40:36.249746+00:00"
            "grade": "A"
            "start_date": "2023-08-04T15:40:36.249746+00:00"
          }
        ]
      }'

GraphQL query create:

{
  create_content_manifest_component_for_manifest(
    id: "abc123"
    input: {
      type: "library", 
      name: "example_name", 
      version: "1.23", 
      purl: "example_purl", 
      build_dependency: false
    }
  ) {
    error {
      status
      detail
    }
    data {
      _id
    }
  }
}

REST call endpoint equivalent post object:

curl -X 'POST' \
 'https://catalog.redhat.com/api/containers/v1/content-manifests/id/abc123/component' \
  -d '{
      "type": "library", 
      "name": "example_name", 
      "version": "1.23", 
      "purl": "example_purl", 
      "build_dependency": false
}'

GraphQL query find:

{
  find_images(
    filter: {
        and: [
            { creation_date: { ge: "2023-06-08T00:00:00.892809+00:00" }}
            { creation_date: { le: "2023-06-08T23:59:59.892809+00:00"}}
            { brew: {package: { ne: "example_package"}}}
        ]
    }
) {
    error {
        status
        detail
    }
    data {
        _id
    }
  }
}

REST call endpoint equivalent get many objects:

curl -X 'GET' \
 'https://catalog.redhat.com/api/containers/v1/images?filter=creation_date>="2023-06-08T00:00:00.892809+00:00" and creation_date<="2023-06-08T23:59:59.892809+00:00" and brew.package!="example_package"&include=data._id'

REST to GraphQL