API basics

This article takes you through the basics of the Prepr GraphQL API.

The API URL

The GraphQL endpoint (API URL) looks like the URL below:

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

When you add an environment, Prepr provides two API endpoints by default, GraphQL Production and GraphQL Preview. The API URL value for each of these is the same for any operation you perform. Check out the Authorization doc for more details.

The HTTP method

In general, the Hypertext Transfer Protocol (HTTP) is how your application and the server communicate. To call the GraphQL API, you will need to use the HTTP POST method with the application/json content type to process larger queries and to send the variables and an operation name along with the query.

Using GET instead of POST

Keep the following points in mind when deciding on the HTTP method:

• Consider using the GET method only if POST doesn't work in your environment.
• While our GraphQL server supports GET for queries, it’s best to keep in mind that lengthy query strings can exceed URL length limits imposed by browsers and CDNs.
• GET can help with HTTP caching, but be cautious with complex operations.

Headers

You can include some HTTP headers in the request, in other words, the key-value pairs to specify the request body format or additional information about the API request. The GraphQL API supports the following list of HTTP headers:

Body

Include a query string with the following properties in the body of the request you send to the API:

• 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.

See an example request below with the following variables:

{
  "postId": "c85aa36b-8796-4f0d-955e-b317f7f905a2",
  "locale": "en-US"
}

query PostQuery($postId: String, $locale: String!){
	Post (id: $postId, locale: $locale, ) { 
		_id
		title
		_slug
	}
}

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 returns an error message in the response. Read more about possible statuses and errors.