Overview of GraphQL

Candid’s Taxonomy API is built using GraphQL. GraphQL is a powerful query language for APIs, and has several notable benefits:

• Returns exactly the data as you’re interested in.
• Reduces the number of requests to get to the data you need.
• Predictable results - provides data in the same structure as it is requested.

📘

GraphQL resources

For more resources, visit GraphQL’s Introduction to GraphQL.

Operations

GraphQL supports several operation types (queries, mutations, and subscriptions). Candid's Taxonomy API makes use of queries only.

Queries

Queries are used to fetch data. Users can specify which fields will be returned by a query, and the resulting data will be returned in the same structure as the query.

Arguments

Arguments can be passed into fields and used to filter or transform the resulting data.

For example, the following example is a query (termsByFacet) that will return PCS terms, using an argument (facet: SUBJECT) to limit results to the Subject facet only. The fields code and name will be returned for each result.

query {
  termsByFacet (facet: SUBJECT) {
    data {
      code
      name
    }
  }
}

Multiple Queries

More than one query can be included in a single call to the API.

Aliases

Aliases can be used to rename a field in the result. This is especially helpful when multiple queries are being used, since argument values are not returned in the results.

For example, the following queries will return all PCS terms in the Subject facet (termsByFacet(facet: SUBJECT)), as well as all PCS terms in the Population facet (termsByFacet(facet: POPULATION)). To differentiate the results of each query, the aliases subjectTerms and populationTerms have been used.

query {
  subjectTerms: termsByFacet(facet: SUBJECT) {
    data {
       code
       name
    }
  }
  populationTerms: termsByFacet(facet: POPULATION) {
    data {
       code
       name
    }
  }
}

Fragments

When the same set of fields is repeated multiple times in a query, it can be helpful to utilize fragments, which are reusable collections of fields.

The below example replaces the fields code and name, which are repeated in the example above, with the fragment codeFields, which can then be referenced in queries.

query {
  subjectTerms: termsByFacet(facet: SUBJECT) {
    data {
       ...codeFields
    }
  }
  populationTerms: termsByFacet(facet: POPULATION) {
    data {
       ...codeFields
    }
  }
}

fragment codeFields on Term {
    code
    name
}