graphql-api.adoc

GraphQL API

Overview

The core module supports a GraphQL API. The API follows the recommendations from the GraphQl specification. For convenience the core module also serves the in-broswer IDE graphiql at the endpoint graphiql.

Configuration

To enable the GraphQL endpoint use the following configuration

graphql.enabled=true

Usage

Start the server and open the graphiql IDE (at http://localhost:9090/graphiql by default). The graphiql is setup to talk to the running instance of LDS.

GraphQL Schema

When GraphQL is enabled, LDS will convert the JSON Schemas to a GraphQL schema.

Using the same examples as in the examples the resulting GraphQL schema will be as follow:

type Person {
  name: String
  addresses(after: String, before: String,
    first: Int, last: Int): PersonAddressConnection
}

type Address {
  street: String
  city: String
}

# [...]

type Query {
  Person(after: String, before: String,
             first: Int, last: Int): PersonConnection
  Address(after: String, before: String,
              first: Int, last: Int): AddressConnection
}

A GraphQL type is defined for each JSON Schema definition as well as a Query field for the type.

Relations are wrapped in connection Type (See next section).

Pagination

The relations and Query fields are wrapped in Connection types as defined in the Relay Cursor Connections Specification.

type PersonConnection {
  edges: [PersonEdge]
  pageInfo: PageInfo
}

type PersonAddressConnection {
  edges: [PersonEdge]
  pageInfo: PageInfo
}

type PersonEdge {
  node: Address
  cursor: String
}

Time versioning

The GraphQL support time versioning. As for the REST API, the desired version is represented by a timestamp parameter. The timestamp value must be encoded as ISO-8601 combined date and time format.

Missing parameter or malformed values will result in using the server current time (ie, latest version).

One can either

• Send a http query parameter timestamp along with the graphql request.

• Add a __timestamp variable in the graphql request.

The query parameter takes precedence over the graphql variable.

Search queries

Additional search capabilities can be enabled with the following configuration:

graphql.search.enabled=true

This will enable a search method and a corresponding search result type that is exemplified in the GraphQl specification. The resulting GraphQL schema will be as follows:

# Several union types may be listed here...
union SearchResult = Agent | AgentInRole | AttributeComponent | ComponentRelationship # [...]

# This should correcpond to the union types listed above
enum TypeFilters {
  Agent
  AgentInRole
  AttributeComponent
  ComponentRelationship
  # ...
}

type SearchResultConnection {
  edges: [SearchResultEdge]
  pageInfo: PageInfo
}

type SearchResultEdge {
  node: SearchResult
  cursor: String
}

type Query {
  Search(after: String, before: String, filter: [TypeFilters], first: Int, last: Int, query: String!): SearchResultConnection
}

When you query a field that returns the SearchResult union type, you need to use a conditional fragment (…​ on TypeName) to be able to query the fields of each type. Also, the result types can be filtered up-front with the filter argument:

{
  Search(query: "test", filter: [Agent, AgentInRole, AttributeComponent])) {
    edges {
      node {
        __typename
        ... on Agent {
          administrativeStatus
        }
        ... on AgentInRole {
          name {
            languageText
          }
        }
        ... on AttributeComponent {
          name {
            languageText
          }
        }
      }
    }
  }
}