GraphQL Documentation

Overview

In addition to the REST-style JSON API, the EHRI portal has an experimental web GraphQL API, intended for retrieving specific EHRI data in structured JSON format. Unlike the REST API, the GraphQL interface does not support search. It does, however, provide more types of data, and is a faster and more efficient option when the data required in known in advance. There is also a GraphiQL interface which provides an interface for building queries and browsing the types of data that is available.

See the GraphQL Docs for an overview of the language's features and semantics.

Usage

Note: Try the GraphiQL interface for a better intractive query experience. Be sure to see the "Docs" section at the right hand side for information on what type and data is available.



Run it as a curl command:

curl --header Content-type:application/json \
                    https://portal.ehri-project.eu/api/graphql \
                    --data-binary '{"query":"\n{\n Country(id: \"us\") {\n name\n situation\n }\n}\n "}'

Data Formats

The GraphQL POST endpoint at /api/graphql accepts data in two formats, specified by the Content-type header:

application/json
A JSON object with, at minumum, a query field containing the text of the query. You can also provide a variables field containing of a JSON object of GraphQL Query Variables
text/plain
The query as text. Variables are not supported via this format.

Pagination and Cursors

By default the GraphQL API returns paginated (partial) data for types which return lists of items. GraphQL types which represent potentially unbounded lists of items, such as repositories or documentaryUnits, contain two sub-fields name items and pageInfo. The items field is an array of items in the current page, and pageInfo contains a nextPage cursor that can be passed to the after argument to retrieve the next page of items. (More generally this pagination schema conforms to the Relay Cursor Connections Specification, with the exception of backwards pagination which is not currently supported.)

This is an example of a query which fetches the items and next page cursor:

In this case, if no variables were provided for the value of the $cursor parameter it would default to null, returning the first page of items. Thereafter the value of nextPage can be used as the $cursor value to retrieve subsequent items.

Streaming

While response pagination is appropriate for user interfaces or memory-constrained applications it is less efficient than retrieving a complete data set as a stream. Streaming can be enabled for the GraphQL API by adding the HTTP header value X-Stream: true to the GraphQL request. In this mode, pagination will be disabled for all list types and the full dataset returned as an HTTP chunked response.

Example usage with Python

The script shown below is a Python script for creating a tab-delimited (TSV) file containing three fields: the EHRI item id, its title, and the history field of EHRI institution descriptions.

You can copy the code to a file called history.py and run it with URL for the EHRI GraphQL API, e.g:

python3 history.py "https://portal.ehri-project.eu/api/graphql"

This will run a query for the history field of repository descriptions, and download and convert the data to TSV in pages of 50 items at a time.