Skip to main content
Version: 0.4

Hub GraphQL API

Capact Hub can be run in two modes: public and local. In a result, GraphQL API for Hub consists of two separate GraphQL schemas:

Public API

Public Hub API contains GraphQL operations for the following entities:

  • RepoMetadata
  • InterfaceGroup
  • Interface
  • Type
  • Implementation
  • Attribute

Currently, there are no GraphQL mutations or subscriptions available. Once populated with DB populator, all resources are read-only.

To see full GraphQL schema, open the schema.graphql file.

Local API

Local Hub API contains GraphQL operations for managing TypeInstances.

To see full GraphQL schema, open the schema.graphql file.

Examples

To run sample GraphQL queries and mutations for Public or Local Hub, follow the steps:

  1. Open the Capact Gateway GraphQL Playground.

    To see how to access the Gateway on development cluster, read the Access Gateway GraphQL Playground section in development guide.

  2. Navigate to a proper directory with GraphQL schema and examples.

    For Public Hub examples, navigate to hub-js/graphql/public directory. For Local Hub examples, navigate to hub-js/graphql/local directory.

  3. Copy and paste the examples.graphql file content to the GraphQL Playground IDE.

  4. Click on the "Query Variables" tab.

  5. Copy and paste the examples.variables.json file content to the Query Variables section of the GraphQL Playground IDE.

  6. Run any query or mutation from the list.

Common flows

The following section showcases a few common usage flows for Hub GraphQL API.

Querying different revisions

For all entities which has revision support, a unified API is available. There are three nested resolvers:

  • accessing the latest revision
  • getting a specific revision
  • getting all revisions

The following example shows the possibilities on Attribute entity:

query {
attributes {
# name, path and prefix are immutable across all revisions of a given node.
name # equal metadata.name, e.g. stateless
path # equal to metadata.path, e.g. cap.core.attribute.workload.stateless
prefix # equal to metadata.prefix, e.g. cap.core.attribute.workload

# the latest revision
latestRevision {
metadata {
name
displayName
}
revision
}

# a given revision
revision(revision: "1.0.0") {
metadata {
name
displayName
}
revision
}

# all revisions
revisions {
metadata {
name
displayName
}
revision
}
}
}

The same unified API is available for all entities.

List InterfaceGroups, that contains Interfaces, which contains Implementations for a given system

To list all InterfaceGroups with nested Interfaces and Implementations for a given system that satisfy the Interfaces, you may use a single GraphQL query.

See the InterfaceGroupsWithInterfacesAndImplementations sample query.

Get Type details along the corresponding TypeInstances

Because of the Hub local and public API separation, currently a single GraphQL query for Types and corresponding TypeInstances is not possible. To achieve that, the following queries have to be executed:

  1. Get Type details with type query to public Hub

    See the Type sample query.

  2. Get TypeInstances for a given Type with typeInstances

    See the ListTypeInstancesWithTypeRefFilter sample query.

Limitations

  • For alpha release, to filter Implementations with the ones that are supported on a given system, client (such as CLI) always send TypeInstances list. In the future, there will be a dedicated query, where the available TypeInstances will be detected automatically and all Implementations will be filtered based on them.
  • For alpha and GA release we don't support revision ranges.