Kundo Knowledge API Documentation

Welcome to the Kundo Knowledge API documentation!

This API is a work in progress, so if you have any questions or feedback, please contact us at support@kundo.se.

Note that to start using the API, we must enable it for you, so send us an email and we will get you started.

JSON API

Kundo Knowledge API uses the JSON API format for all requests.

This means that all requests to the API should include the Accept: application/vnd.api+json HTTP header without any modifications, as specified under "Client responsibilities" in the above link.

Calls that do not provide Accept: application/vnd.api+json will receive a 406 Not Acceptable response.

The api server will reply with Content-Type: application/vnd.api+json for all successful calls.

Data Types

This section lists and explains the different resources that Kundo Knowledge API handles.

Each data type has some attributes it exposes and a list of relationships.

NOTE: Relationships on a resource will only be populated if the related resource is specified as an included type (see "Included Types").

KnowledgeBase

Attributes

Relations

Guide

Attributes

Relations

Category

Attributes

Relations

Tag

Attributes

Relations

Endpoints

Knowledge bases

Fetch information about a knowledge base

Guides

List guides

Filtering guides

Lists of guides can be filtered by either a category or a tag.

Filtering is done by the filter query parameter, like so:

GET /knowledge/v1/kb.kundo.se/guides?filter[:filter_type]=:filter_value

NOTE: filtering by both category and tag is not supported. If a request specifies both tag and category filters, the API will use the first filter specified.

Given ?filter[tag]=foo&filter[category]=bar, the API will return the same result as if only given ?filter[tag]=foo.

Filtering by tag

Filtering a guide list by tag is done using the tag filter type:

GET /knowledge/v1/kb.kundo.se/guides?filter[tag]=foo

This request will return guides tagged with the "foo" tag.

Filtering by category

Filtering a guide list by category is done using the category filter type:

GET /knowledge/v1/kb.kundo.se/guides?filter[category]=foo

This request will return guides categorized with the "foo" category.

Search guides

It is possible to search in a knowledge base's guides. This is done using the q query parameter:

GET /knowledge/v1/kb.kundo.se/guides?q=foo

This will return all guides matching the search query "foo". That is all guides that has the search string "foo" anywhere in their title or content_html field.

The search engine uses some language analysis to make queries a bit smarter. For example, this means that if you search for "queries", the result will match not only documents containing the word "queries" but also documents matching the base form "query".

Vote for a guide

It is possible to give feedback to a guide, either positive or negative feedback, by voting on it. You can either upvote a guide, or downvote it. These requests are done like so:

Fetch a guide

GET /knowledge/v1/kb.kundo.se/guides/2
GET /knowledge/v1/kb.kundo.se/guides/slug/my-guide-slug

Returns:

{
  "data" : {
    "attributes" : {
      "content_html" : "...",
      "title" : "Lägg till ny inkorg i Kundo Mail",
      "slug" : "komma-igang-med-kundo-mail"
    },
    "id" : "500",
    "type" : "guide",
    "relationships" : {
      "knowledge_base" : {},
      "tags" : {},
      "categories" : {}
    },
    "links" : {
      "self" : "/knowledge/v1/kb.kundo.se/guides/500"
    }
},
"jsonapi" : {
  "version" : "1.0"
}

Sparse fieldsets

If you don't want to retrieve all fields on a resource when fetching data from the API, you can use the "Sparse fieldset" feature of JSON API to specify which fields you are interested in.

Example: Fetch the title and slug of all guides

GET /knowledge/v1/kb.kundo.se/guides?fields[guide]=title,slug

This will return a list of guides with only the title and slug fields populated. This specific example can be used to get a list of guides without having to send all guide content data.

Included types

It is possible to retrieve a resource along with related resources.

Included resources will be returned under the included key in the response.

This is done by specifying the include query parameter, like so:

GET /knowledge/v1/kb.kundo.se/guides?include=knowledge_base
{
  "jsonapi" : {
    "version" : "1.0"
  },
  "data" : [
    {
        "type" : "guide",
        "links" : {
          "self" : "/knowledge/v1/kb.kundo.se/guides/500"
        },
        "attributes" : {
          "slug" : "komma-igang-med-kundo-mail",
          "title" : "Lägg till ny inkorg i Kundo Mail",
          "content_html": "..."
        },
        "id" : "500",
        "relationships" : {
          "categories" : {},
          "tags" : {},
          "knowledge_base" : {}
        }
    },
    ... <more guide objects>
  ],
  "included": [
    {
      "data" : {
        "relationships" : {
          "tags" : {},
          "guides" : {},
          "categories" : {}
        },
        "type" : "knowledge_base",
        "attributes" : {
          "host" : "kb.kundo.se",
          "name" : "Kunskapsbanken",
          "organization_name" : "Kundo"
        },
        "id" : "1",
        "links" : {
          "self" : "/knowledge/v1/kb.kundo.se"
        }
      }
    }
  ]
}

Caching

Kundo Knowledge API uses HTTP Etags for caching. This means that for every request sent to the API, the response will come with an etag header that can be used when performing that same request again.

For clients who want to cache the data received from the API, they should make sure to also cache the etag response header, so that they can send that as the if-none-match request header when making subsequent calls to those resources.

If you request /knowledge/v1/kb.kundo.se, you will receive an etag response header with some value, e.g. "ABCDEFGHI123456789".

When making subsequent requests to that same resource, you can (should) send that etag value as the if-none-match request header. If the resource has not been modified since your last request, you will receive a "304 Not Modified" response and no data.