YOUnite Server GraphQL API Reference

Overview

The YOUnite GraphQL API interface allows access to:

YOUnite data such as zones, domains, etc.
YOUnite Data Store data
The YOUnite Data Virtualization service and federated data record assembly

The GraphQL Schema

The GraphQL schema includes pre-defined queries (adaptors, domains, zones, etc) as well as dynamically built queries and types for accessing data records. The schema can be retrieved via the graphql-schema REST endpoint, ie GET http://younite-server:8080/api/graphql-schema. Note that authentication is required, like all other REST API endpoints.

The schema is a standard GraphQL schema with types, scalars and directives. For example (this is just a small excerpt showing the Domain and DomainVersion types and the Query fields that can be used to retrieve them):

... various directives and types ...

type Domain {
  active: Boolean
  changeVersion: Long
  createdByUuid: Uuid
  dateCreated: DateTime!
  defaultVersion: DomainVersion
  defaultVersionNumber: Long
  defaultVersionUuid: Uuid
  description: String
  domainType: Domain_DomainType
  lastUpdated: DateTime!
  name: String
  uuid: ID!
  versionCount: Long
  versions: [DomainVersion]
}

type DomainVersion {
  changeVersion: Long
  createdByUuid: Uuid
  dateCreated: DateTime!
  description: String
  domain: Domain
  drKeyProperties: [String]
  lastUpdated: DateTime!
  matchingAlgorithm: MatchingAlgorithm
  modelSchema: Json
  uuid: ID!
  versionNumber: Long
}

type DomainVersions {
  data: [DomainVersion]!
  page: Page!
}

type Domains {
  data: [Domain]!
  page: Page!
}

type Query {
  domainVersions(domainName: String, domainUuid: Uuid, domainVersionUuid: Uuid, page: Int! = 0, size: Int! = 50, versionNumber: Long): DomainVersions!
  domains(domainName: String, domainUuid: Uuid, page: Int! = 0, size: Int! = 50): Domains!
}

enum Domain_DomainType {
  FEDERATED
  YOUNITE_DATA_STORE
}

"An RFC-3339 compliant DateTime Scalar"
scalar DateTime

"JSON-encoded String"
scalar Json

"Long type"
scalar Long

"UUID"
scalar Uuid

Executing a Query

GraphQL queries are served by the YOUnite Server via HTTP just like the REST API endpoints. Queries are performed by calling GET or POST on the graphql endpoint. Note that authentication is required, like all other API endpoints.

GET Example:

GET http://younite-server:8080/graphql?query={adaptors{data{uuid name} page {page size totalPages totalElements}}}

POST Example with variables:

POST http://younite-server:8080/graphql

{
  "query": "query getAdaptors($zoneName: String!) { adaptors(zoneName: $zoneName) { data { uuid name description } } page { page size totalPages totalElements } } }",
  "variables": {
    "zoneName":"My Zone"
  }
}

See GraphQL - Serving over HTTP for more details about executing GraphQL queries over HTTP.

Pagination

Query fields that return paged results accept two parameters: page and size. Note that page is zero based, ie page 0 is the first page. The result of a paged result contains two fields: data and size. data is a list of records returned and page contains pagination information. Example:

Query:

{
    domains(page: 0, size: 2) {
        data {
            uuid
            name
        }
        page {
            page
            size
            totalPages
            totalElements
        }
    }
}

Result:

{
    "data": {
        "domains": {
            "data": [
                {
                    "uuid": "ff107c3c-1ff1-474d-878c-c411bbedf1b4",
                    "name": "product"
                },
                {
                    "uuid": "3f855587-9c7f-4b70-8286-bf9bb6065d81",
                    "name": "purchaseOrder"
                }
            ],
            "page": {
                "page": 0,
                "size": 2,
                "totalPages": 10,
                "totalElements": 19
            }
        }
    }
}

Querying Tools

A tool such as Postman makes querying much easier. Below is a screenshot example of using Postman to query domains:

Querying Data Records

Note	This section assumes familiarity with retrieving data records. See Accessing Data Records before reading this section.

Data Store records as well as Federated data records can be queried with GraphQL. The functionality is the same as what can be done with the regular rest API calls with one important enhancement:

Cross-referenced records in Federated data models can be retrieved using selection criteria (or in other words, a join condition). The criteria is in Lucene syntax.

Naming convention

Query fields for domains are in the syntax dr_[domain name]_[domain version] such as dr_customer_1.

Retrieving Data Store Records

Data Store queries accept the following arguments:

page = page number (zero based)
size = page size
query = Lucene query to select records. May ONLY reference DR Key properties. See Accessing Data Records for more information on lucene queries
sort = Sort criteria. A comma-separated list of fields. May ONLY reference DR Key properties. A minus (-) sign in front of a field name indicates descending order.

Example:

{
    dr_part_1(query: "code:W*", sort:"code", page: 0, size: 10) {
        data {
            code
            name
        }
        page {
            page
            size
            totalPages
            totalElements
        }
    }
}

Result:

{
    "data": {
        "dr_part_1": {
            "data": [
                {
                    "code": "WDG",
                    "name": "Widget"
                }
            ],
            "page": {
                "page": 0,
                "size": 10,
                "totalPages": 1,
                "totalElements": 1
            }
        }
    }
}

Retrieving Federated Data Records

Federated data records can be assembled much in the same way as Data Store Records above, with some additional options. These options match the options available via the normal REST API call (see Accessing Data Records).

page = page number (zero based)
size = page size
zoneUuid = The zone UUID for which to run the query. If not specified, the default zone UUID of the logged in user is used.
drUuids = List of DR UUIDs to assemble.
query = Lucene query to select records. May ONLY reference DR Key properties. See Accessing Data Records for more information on lucene queries
sort = Sort criteria. A comma-separated list of fields. May ONLY reference DR Key properties. A minus (-) sign in front of a field name indicates descending order.
additionalParameters = JSON-encoded String with additional parameters to send to the assembler. Can include any of the assembler options not referenced above (see Accessing Data Records).

Example:

{
    dr_employee_1(zoneUuid: "6c5a754b-6ce0-4871-8dec-d39e255eccc3", query: "lastName:B* OR lastName:S*", sort:"lastName", page: 0, size: 10) {
        data {
            lastName
            firstName
        }
        page {
            page
            size
            totalPages
            totalElements
        }
    }
}

Result:

{
    "data": {
        "dr_employee_1": {
            "data": [
                {
                    "lastName": "Berlin",
                    "firstName": "Tobey"
                },
                {
                    "lastName": "Bromage",
                    "firstName": "Bevan"
                },
                {
                    "lastName": "Schmitt",
                    "firstName": "Rollie"
                }
            ],
            "page": {
                "page": 0,
                "size": 10,
                "totalPages": 1,
                "totalElements": 3
            }
        }
    }
}

Retrieved Cross-Referenced Records

Cross-referenced data can be referenced by specifying a Lucene query to use to choose the linked record or records. Fields from the parent record can be referenced in the query with the syntax ${field name}.

Example

Notes:

This example also shows using additionalParameters to specify which adaptor(s) to use to assemble the data.
The employee domain has a field classificationCode which is going to be used to cross-reference with the employeeClassification domain, retrieving its description field. See schema below.
The employee domain has a field managerEmployeeId which is going to be used to cross-reference with the employee domain. See schema below.

Schema of Employee

{
  "employeeId": {
    "type": "string"
  },
  "firstName": {
    "type": "string"
  },
  "lastName": {
    "type": "string"
  },
  "manager": {
    "$ref": "/domains/employee:v1"
  },
  "managerEmployeeId": {
    "type": "string"
  },
  "classification": {
    "$ref": "/domains/employeeClassification:v1/description"
  },
  "classificationCode": {
    "type": "string"
  }
}

Example Query:

{
    dr_employee_1(query: "firstName:James OR firstName:Artemus", additionalParameters: "{\"adaptors\":[\"3a7f6cbf-ddee-4fed-ac8a-952973877dcb\"]}") {
        data {
            lastName
            firstName
            classificationCode
            classification(query: "code:${classificationCode}")
            managerEmployeeId
            manager(query: "employeeId:${managerEmployeeId}") {
                lastName
            }
        }
        page {
            page
            size
            totalPages
            totalElements
        }
    }
}

Result:

{
    "data": {
        "dr_employee_1": {
            "data": [
                {
                    "lastName": "West",
                    "firstName": "James",
                    "classificationCode": "PT",
                    "classification": "Part-time employee",
                    "managerEmployeeId": "1E75908KLD",
                    "manager": {
                        "lastName": "Schmitt"
                    }
                },
                {
                    "lastName": "Gordon",
                    "firstName": "Artemus",
                    "classificationCode": "CO",
                    "classification": "Contractor",
                    "managerEmployeeId": "1E67052TIY",
                    "manager": {
                        "lastName": "West"
                    }
                }
            ],
            "page": {
                "page": 0,
                "size": 50,
                "totalPages": 1,
                "totalElements": 2
            }
        }
    }
}