API basics

Check out this article to learn the basics of GraphQL API.

The API URL

The GraphQL endpoint will look similar to the URL below:

https://graphql.prepr.io/<YOUR-ACCESS-TOKEN>

By default, there are two API endpoints per environment – Preview and Published. Once generated, the API URL remains constant no matter what operation you perform.

Read more in Authorization.

The HTTP method

In general, the Hypertext Transfer Protocol (HTTP) is the underlying format that is used to structure requests and responses for effective communication between an application and a server.

To call the GraphQL API, you will need to use the HTTP POST method with the application/json content type as it allows processing larger queries and sending the variables and an operation name along with the query.

The Headers

Requests to the GraphQL API can include some HTTP headers — the key-value pairs to specify the request body format or provide additional information about the API request, for example, the Customer ID for retrieving personalized content or running an A/B test.

The Body

The request body should include a query string you send to the API, including the following properties:

  • query — the full GraphQL query containing the operation type (currently, only the query type is supported), the types & fields requested, and any variables included.
  • operationName — optional, but if included, must be present in the query.
  • variables — optional if there are no variables included in the query.

Here’s an example request:

query PostPageQuery($id : String!) {
          post: Post( id : $id) {
              title
              summary
          }
      }
{
"data": {
  "post": {
    "title": "Australian of the Year 2021 Grace Tame’s powerful message on Q&A",
    "summary": "Quisque fermentum massa ac auctor tempus..."
  }
}
}

The GraphQL API will validate and execute this query string and return a response in JSON format.

When a query contains a mistake, the API might return an error message in the response. Read more about possible statuses and errors.