Kaddio GraphQL API - kaddio/documentation GitHub Wiki

Prerequisites 🤓

To implement and use any of Kaddios API's, you need the following:

API Add-on module

You need an active account with Kaddio and at least the Kaddio API add-on module.

Understanding of Kaddio

You need a basic understanding of the concepts of Kaddio and it's data models. Please refer to https://help.kaddio.com or reach out to an administrator in your organisation.

Web technologies

You need intermediate knowledge of web technologies like HTML and Javascript.

Getting started

The Kaddio API is a GraphQL based API that lets you do some of the common tasks available in Kaddio. It is based on the presumption that the API should only do things that are possible to do as a regular user of Kaddio, and the operations available are limited to this assumption. This means that the API user does not has direct write access to the Notes collection, instead it is available in the same way as for the end user, namely by adding it to a Contact. This idea also affects how operations are run - they are always run as a specific person, just as an ordinary user always is a person. In this way you don't provide the id of the host that is connected to a Contact, instead you call createContact as this host. Examples of this will be provided later in these docs.

Send an email to [email protected] describing your use case and how you plan on using the API and we'll get you started in no time!

Enable

Kaddio API is an add-on module which can be activated from within your Kaddio Organization Settings. When the API is enabled you can access the GraphQL endpoints, it also allows you to obtain access tokens.

Find

The api is called by posting to https://[url].kaddio.com/graphql. A playground for testing operations exists at the same adress. In the playground you can see the docs for the queries and mutations available.

Authorize

Kaddio has a system with personal tokens that can be generated on your personal profile page /my-profile. Click on New token and copy the contents. Then you can use the API with the following HTTP-headers:

{
	"Authorization":"my_secret_token"
}

If you are an admin your token can be used in conjunction with the id of an other host which can be used to call methods as the other person:

{
  "Authorization":"my_secret_token",
  "ImpersonationId":"id_of_the_other_user"
}

A full curl might look like

curl 'https://[url].kaddio.com/graphql' -H 'Content-Type: application/json' -H 'Authorization: secret_token' -d 'query'

Rate limiting

The API has two different mechanisms for handling rate limiting.

• Maximum concurrent requests is 2 per organization. This protects if someone sends a burst of requests, which might be to much even if the requests are cheap.
• A Sliding Window algorithm. In every 10 s window every organization can have at most 5 seconds of execution time. This protects from a general high load over time.

This means that if you would like to do big batch operations you'll have to implement them so that they sleep on your side half of the time.

Hooks

In order to receive a callback when something happens in Kaddio, a hook can be used. Kaddios hooks are based on changes on collections rather than on events. Instead of listening to the contact.sign method you add a hooks that listens to contacts.update with the query {isSigned: true}. The query here is just an ordinary query as in the find-methods. This gives a lot of flexibility in terms of what hooks are possible.

The query works as follows:

• INSERT: triggered if the query matches the document to be inserted
• UPDATE: triggered if the "diffdocument" between old and new value matches
• REMOVE: triggered if the query matches the document to be removed

Examples

query {
  findUsers(filter: {isHost: {EQ: true}}) {
    _id
    firstname
  }
}

{
  "data": {
    "findUsers": [
      {
        "_id": "F8vC8R3egRDv7XDzX",
        "firstname": "Marina"
      },
      {
        "_id": "HbxAiQsfi4yoty5kE",
        "firstname": "Christine"
      },
      {
        "_id": "gG8GR6wZ4uzggYACr",
        "firstname": "Ali"
      }
    ]
  }
}

query {
  findUsers(filter: {isClient: {EQ: true}}) {
    _id
    firstname
  }
}

  "data": {
    "findUsers": [
      {
        "_id": "NTFeo9LR2vkdf8WHL",
        "firstname": "Kajsa"
      },
      {
        "_id": "PJ7vYCHFEXXn63L2J",
        "firstname": "Pelle"
      }
    ]
  }
}

mutatation {
  clientArrived(bookingId: "mg24fjwjhviehfoifyci") 
  {
  }
}