Using the Highnote API

As mentioned in Intro to GraphQL, an example ping query to the Highnote API looks like this:

Copy code snippet
curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic <API_KEY>' \
--data '{"query":"query Ping {\n  ping\n}"}' \
https://api.us.test.highnote.com/graphql

and will return a JSON payload with the following format:

Copy code snippet
{
  "data": {
    "ping": "pong"
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

This guide breaks down this query and its response to provide guidance on using the Highnote API.

Lines 2 and 3 of our example ping query are headers. The Highnote API requires Authorization and Content-Type headers.

Content Type

The Highnote API accepts and returns JSON. To call the Highnote API, you must pass a Content-Type header with the value of application/json:

Copy code snippet
'Content-Type: application/json'

Authorization

Highnote API requests are authenticated using Basic auth. Using Basic auth, your API Key is provided as the username, and a password is not required. API Keys are created in the Dashboard. To obtain an API Key, see Creating and Managing API Keys.

Once you have obtained an API Key, to make a request, pass an Authorization header with your base64 encoded API key:

Copy code snippet
'Authorization': 'Basic <base64_encoded_api_key>'

Requests with missing or invalid credentials will receive a 401 Unauthorized response code.

In our ping query example, the request body is displayed on line 4. The Highnote GraphQL API accepts POST requests with JSON payloads. The requests must contain a string named query, but can also contain variables and operationName.

Query

The query is the GraphQL operation that you are calling:

Copy code snippet
{
  "query": "{ ping }"
}

You can make multiple GraphQL "requests" in a single call. In this case, you would still provide a single query value with all calls as a string.

Our example ping query has a Request URL on line 5. Request URLs used for the Highnote API differ depending on your environment. The endpoint of the URLs will both be /graphql, but the sub-domain will differ:

The following HTTP status codes will be returned from the API:

Read more about GraphQL responses and formats in the spec.

The Response Body contains the data requested from the API endpoint. Read more about GraphQL responses and formats in the spec.

The Highnote API returns JSON response bodies. The responses will contain the following:

If you need help with a response, see troubleshooting with Request IDs in the Highnote API.