GraphQL Documentation

Run it as a curl command:

curl --header Content-type:application/json \
                    https://portal.ehri-project-stage.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.