Home / GraphQL API
The URL used for the Highnote API depends on your environment. The endpoint will be /graphql
, but the sub-domain will differ.
https://api.us.test.highnote.com/graphql
https://api.us.highnote.com/graphql
Highnote API requests are authenticated using Basic auth where your API Key is provided as the username. A password is not required. See below for details on obtaining API keys.
To make a request, pass an Authorization
header with your base64 encoded API key.
Requests sent with missing or invalid credentials will receive a 401 Unauthorized
response code.
You can obtain an API key via the Highnote Dashboard by navigating to API Keys
in Developers, and creating a new key. If you don't yet have a Highnote account, you can sign up for one.
The newly generated key will only be presented once and cannot be retrieved later. API keys can be revoked at any time via the Highnote Dashboard.
'Authorization': 'Basic <base64_encoded_api_key>'
curl -X POST \ -H 'Content-Type: application/json' \ -H 'Authorization: Basic <base64_encoded_api_key>' \ --data '{"query":"query Ping {\n ping\n}"}' \ https://api.us.test.highnote.com/graphql
The Highnote API requires Authorization
and Content-Type
headers. Since the API accepts and returns JSON, pass a Content-Type
header with the value of application/json
.
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 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. |
More about troubleshooting with Request IDs in the Highnote API.
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 (query, mutation, etc.) 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.
{ "query": "query Ping {\n ping\n ping2: ping\n}" }
The variables
field is used to pass dynamic input to queries and mutations.
Here is an example of passing variables to the IssuePaymentCard
mutation.
mutation IssuePaymentCard($input: IssuePaymentCardInput!) { issuePaymentCard(input: $input) { ... on PaymentCard { id } } }
For this mutation, the payload would be created like this:
const payload = JSON.stringify({ query: ` mutation IssuePaymentCard($input: IssuePaymentCardInput!) { issuePaymentCard(input: $input) { ... on PaymentCard { id } } } `, variables: { input: { cardholderId: "cardholder_id", cardProductId: "card_product_id", options: { activateOnCreate: true, expirationDate: "2022-01-01T23:59:59Z", }, }, }, });
Learn more about using variables in GraphQL.
In the case that you have a GraphQL document that contains multiple operations, you can use operationName
to tell the server which to execute. For example, given the following GraphQL with both IssuePaymentCard
and Ping
, to run Ping
, you would provide HelloWorld
as the operationName
on your payload:
GraphQL document:
query HelloWorld { ping } mutation IssuePaymentCard($input: IssuePaymentCardInput!) { issuePaymentCard(input: $input) { ... on PaymentCard { id } } }
Payload:
{ "query": "...", "operationName": "HelloWorld" }
Read more about using operationName
here.