Skip to main content

Using the Highnote API

Before you start​

This guide uses a simple cURL command to demonstrate how to query the Highnote API. Our command sends a ping query:

curl --request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_API_KEY' \
--data '{"query":"query {ping}"}' \
https://api.us.test.highnote.com/graphql

A slash \ represents a newline. Also, options can be represented in single-dash format (which you may see throughout the Highnote docs):

curl -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YOUR_BASE64_ENCODED_API_KEY' \
-d '{"query":"query {ping}"}' \
https://api.us.test.highnote.com/graphql

If successful, the ping query returns the following JSON payload (with the rateLimit info removed for simplicity):

{ "data": { "ping": "pong" }, "extensions": { "requestId": "REQUEST_ID" } }

Headers​

The Highnote API requires the following headers:

  • Content-Type
  • Authorization

Content type​

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

--header 'Content-Type: application/json'

Authorization​

The Highnote API uses Basic authentication which requires a base64-encoded API key (that is set as the username and does not require a password).

To create a base64-encoded API key:

  1. Create an API key in the Highnote Dashboard. This key is ASCII-encoded. See Creating and Managing API Keys.

  2. Convert your API key from ASCII to base64:

    echo -n 'YOUR_ASCII_ENCODED_API_KEY' | base64

  3. Pass your base64-encoded key with the Authorization header using the Basic scheme:

    --header 'Authorization: Basic YOUR_BASE64_ENCODED_API_KEY'
info

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

Request body​

The Highnote API accepts POST requests with JSON payloads. Requests include:

FieldDescription
query or mutation (required)Defines the request operation
variables (optional)JSON payload passing dynamic data in a request
Operation name (optional)Name of the request, esp. useful when running many

In our ping query example, the request body is on line 4:

--data '{"query":"query {ping}"}'

The following code snippet makes the same simple query. To run the query, sign in and expand "Variables", then watch the requestId change with each call.

query {
  ping
}
{
  "data": {
    "ping": "pong"
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Operation name​

You can add an operation name (conventionally in PascalCase); for example, we can name our query PingPong:

curl --request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_API_KEY' \
--data '{"query":"query PingPong {ping}"}' \
https://api.us.test.highnote.com/graphql
query PingPong {
  ping
}
{
  "data": {
    "ping": "pong"
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Variables​

The ping query doesn't take any arguments, so we cannot use it to test variables; but we can test the node query which does accept them.

  • Query that tries to get a node with id = node_123abc (and which probably returns null):
--data '{
 "query": "query { node(id: \"node_123abc\") { id } }"
}'
  • Query with the operation name, GetNode
--data '{
 "query": "query GetNode { node(id: \"node_123abc\") { id } }"
}'
  • Query with a variable for the id:
curl --request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_API_KEY' \
--data '{
 "query": "query GetNode($id: ID!) { node(id: $id) { id } }",
 "variables": {
   "id": "node_123abc"
 }
}'  \
https://api.us.test.highnote.com/graphql

The following code snippets makes the same query:

query GetNode($id: ID!) {
  node(id: $id) {
    id
  }
}
{ "id": "node_123abc" }
{
  "data": {
    "node": null
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Multiple requests​

You can make multiple GraphQL requests in one by providing a single query value with multiple calls as a string, for example, ping and organizations:

curl --request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic YOUR_BASE64_ENCODED_API_KEY' \
--data '{
 "query": "query { ping organizations { id profile { displayName } } }"
}' \
https://api.us.test.highnote.com/graphql
query {
  ping
  organizations {
    id
    profile {
      displayName
    }
  }
}
{
  "data": {
    "ping": "pong",
    "organizations": [
      {
        "id": "ORG_ID",
        "profile": {
          "displayName": "ORG_NAME"
        }
      }
    ]
  },
  "extensions": {
    "requestId": "REQUEST_ID"
  }
}

Request URL​

The Highnote API has a unique URL for its Live and Test environments. Both environments use a graphql endpoint but with a different subdomain.

Our sample ping query has a request URL on line 5 for the Test environment.

https://api.us.test.highnote.com/graphql
# Test Environment Request URL
https://api.us.test.highnote.com/graphql

# Live Environment Request URL
https://api.us.highnote.com/graphql

Status codes​

Unlike REST, GraphQL often returns a 200 OK status code even when there are errors. For error handling, the response includes an errors object with detailed information for troubleshooting.
For mutations, request the userError type on the union type for specific details about the failure. See error handling for more information.

There are a few non 200 status codes that Highnote’s GraphQL API returns for the following cases:

Status CodeScenario
200 OKGraphQL request was successful or validation/logic errors occurred. See error handling for more information.
400 Bad RequestGraphQL validation failed, usually because of malformed input or selection sets. In this case, the errors collection will be on the response body.
401 UnauthorizedCredentials are invalid.
5xxSomething is wrong on the Highnote side.

Response bodies​

The response body of a query contains the data requested from the API endpoint. A Highnote API response body contains the following in JSON format:

FieldDescription
dataResult of the given operation(s). Reflects the shape of your selection on the query.
errorsReturns if the GraphQL engine fails to parse or validate the given request.
extensionsMap of data custom to a GraphQL implementation. The Highnote API includes a requestId for debugging and rateLimit info which we have been removing for simplicity.
tip

You can format the response body in pretty JSON by installing install jq and editing the URL in your cURL command as follows: https://api.us.test.highnote.com/graphql | jq -C '.'

References: