Overview

​

GraphiQL IDE

Play around with our GraphQL playground in real-time:

​

SDKs

We provide SDKs which make it easier for you to use the functionalities of the API in the languages that you use. Here’s what’s currently available:

You can install these SDKs like so:

// CLI
npm i @usekana/admin-kana-js

// package.json - ensure the following is present:
"dependencies": {
    "@usekana/admin-kana-js": "^0.1.14"
}

​

Endpoint

The GraphQL API has a single endpoint which remains the same no matter what operation you perform:

https://api.usekana.com/graphql

​

Authorization

The Kana API uses API Keys to authenticate requests. You can view and manage your API Keys in the Kana dashboard. Your API Key must be present for all requests made, otherwise your requests will fail.

curl https://api.usekana.com/graphql \

-X POST \

-H "Authorization: INSERT_API_KEY" \

-d '{ "query": "mutation { createFeature(featureIdentifier: "seats-test", name: "Seats Test") { identifier name } }" }'

curl https://api.usekana.com/graphql \

-X POST \

-H "Authorization: INSERT_API_KEY" \

-d '{ "query": "mutation { createFeature(featureIdentifier: "seats-test", name: "Seats Test") { identifier name } }" }'

import { KanaAdmin } from "@usekana/admin-kana-js";

const kanaAdmin = new KanaAdmin({
  apiKey: API_KEY, // Replace with own Private API Key
});

​

HTTP Request Methods

Our GraphQL API only supports POST HTTP requests - you will need to use POST as this enables you to include a JSON-encoded body for the query.

​

Formatting Queries

When submitting a request outside of the GraphiQL IDE, the value of query in the JSON payload needs to be a string containing the GraphQL operation. Here’s an example:

cURL -d '{ "query": "mutation { createFeature(featureIdentifier: "seats", name: "Seats") { identifier } }" }'

​

Errors

We return errors under a different key and with a different type depending on if you’re querying the API directly (ie. cURL) or via one of our SDKs.

​

Handling Errors

You can provide the onError argument with an async function when initializing the client in order to globally take actions when errors occur. The following example logs all errors upon one occurring:

const adminClient = new KanaAdmin({
    apiKey: API_KEY // Replace with own Private API Key
    onError: async (err) => {
        console.log(err);  // or push errors to a central logger
    }
});

If using Typescript, errors will be typed and you can check against this type. The following error types are possible:

• SubscriptionError

• SubscriptionNotFoundError

• PackageNotFoundError

• FeatureNotFoundError

• UserNotFoundError

• AuthenticationError

• NetworkError

• Error

​

Retrying Upon Errors

By default, we will retry sending all calls up to 2 times when a NetworkError occurs with no backoff or delay. You can override this behaviour with the retry argument:

const adminClient = new KanaAdmin({
    apiKey: API_KEY // Replace with own Private API Key
    retry: (error: Error, retryNumber: number) => {
        return error instanceof NetworkError && retryNumber < 3;
    }
});