Home / Highnote API
As mentioned in Intro to GraphQL, an example ping
query to the Highnote API looks like this:
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:
{ "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.
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
:
'Content-Type: application/json'
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:
'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
.
The query
is the GraphQL operation that you are calling:
{ "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:
https://api.us.test.highnote.com/graphql
https://api.us.highnote.com/graphql
The following HTTP status codes will be returned from the API:
Status Code | Scenario |
---|---|
200 OK | GraphQL request was successful or validation/logic errors occurred. See error handling for more. |
400 Bad Request | GraphQL validation failed. This is generally because of malformed input or selection sets. In this case, the errors collection will be present on the response body. |
401 Unauthorized | Returned when invalid credentials are present. |
5xx | Something is wrong on the Highnote side. |
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:
Response Body | Description |
---|---|
data | The result of the given operation(s). This data will reflect the shape of your selection on the query. |
errors | The errors collection will be present if the GraphQL engine failed to parse or validate the given request. Read more about errors in the spec. |
extensions | The extensions field is a map of data custom to a GraphQL implementation. For the Highnote API, the extensions field will contain a requestId for use in debugging or support scenarios. |
If you need help with a response, see troubleshooting with Request IDs in the Highnote API.