Graphql schema documentation
link Overview
Here are some quick links to get you up and running with the GraphQL API:
link Xray Cloud Graphql API endpoint
The Xray GraphQL API has a single endpoint:
https://xray.cloud.getxray.app/api/v2/graphql
The endpoint remains constant no matter what operation you perform.
link Discovering the Xray Cloud GraphQL API
GraphQL is introspective. This means you can query a GraphQL schema for details about itself.
- Query
__schema
to list all types defined in the schema and get details about each:
query {
__schema {
types {
name
kind
description
fields {
name
}
}
}
}
- Query
__type
to get details about any type:
query {
__type(name: "Test") {
name
kind
description
fields {
name
}
}
}
For more information about performing queries, see "Queries and Mutations."
link Xray Cloud GraphQL resource limitations
As with any public API, the Xray Cloud GraphQL API protects against excessive or abusive calls to Xray Cloud's servers.
Node limit
To pass schema validation, all Xray Cloud GraphQL API calls must meet these standards:
- Clients must supply a
limit
argument on any connection. - Values of
limit
must be within 1-100. - Individual calls cannot request more than 10,000 total items.
Calculating items in a call
These two examples show how to calculate the total number of items in a call.
{
getTests(limit: 50) {
total
start
limit
results {
issueId
projectId
preconditions(limit: 10) {
total
start
limit
results {
issueId
projectId
}
}
}
}
}
Calculation:
50 = 50 test issues
+
50 x 10 = 500 precondition issues
= 550 total items
{
getTests(limit: 50) {
total
start
limit
results {
issueId
projectId
preconditions(limit: 10) {
total
start
limit
results {
issueId
projectId
}
}
testRuns(limit: 50) {
total
start
limit
results {
id
status {
name
description
color
}
testExecution {
issueId
projectId
testPlans(limit: 5) {
total
start
limit
results {
issueId
projectId
}
}
}
}
}
}
}
}
Calculation:
50 = 50 tests
+
50 x 10 = 500 preconditions
+
50 x 50 = 2,500 test runs
+
50 x 50 x 5 = 12,500 test plans
= 15,550 total items
Resolver limit
To pass schema validation, all Xray Cloud GraphQL API calls must meet these standards:
- Individual calls cannot use more than 25 resolvers.
Calculating resolvers in a call
These example show how to calculate the total number of resolvers in a call.
Query:
{
getTestSets(limit: 50) {
results {
issueId
projectId
tests(limit: 10) {
results {
issueId
projectId
testType {
name
}
status {
name
}
preconditions(limit: 10) {
results {
issueId
projectId
}
}
}
}
}
}
}
Calculation:
getTestSets + tests + testType + status + preconditions = 5 resolvers
Connection
Connections let you query related objects as part of the same call. With connections, you can use a single GraphQL call where you would have to use multiple calls to a REST API.
It's helpful to picture a graph: dots connected by lines. The dots are nodes, the lines are edges. A connection defines a relationship between nodes.
Item
Item is a generic term for an object. You can look up a item directly, or you can access
related
items via a connection. If you specify a item
that does not return a scalar,
you must include subfields until all fields return scalars.
Resolver
Resolver is a generic term for a query, mutation or complex field. A complex field is any field in Xray Cloud GraphQL API that is not a scalar with the exception of the fields results.
link Guides and other useful links
Here are some links that provide extra information and tools related with GraphQL:
- Grahpql Documentation - here you can find general information about all aspects of GrahpQL.
- Insomnia - a powerful HTTP client with native GraphQL support.