API Introduction

Getting started with the IKANOW API

Overview

The IKANOW API consists of a set of callable RESTful endpoints.

To perform an action using the IKANOW API, you need to select the appropriate endpoint to service your request based on your need and provide the specified arguments. Documentation is available for each method specifying the required parameters for the request and the expected format of the response. If you require additional calls please contact us at support@ikanow.com. 

JSONP is supported via the global URL parameter "jsonp=<callback-name>" (but only if a permanent or temporary API key is used - in fact cross domain is only possible in these 2 cases, with or without jsonp).

Any url attribute can be replaced by a variable name prefixed with '$' e.g. $variable and that variable be declared in the queryArguments of a url string e.g. ?variable=some%20value.  This is useful for long requests that cause Restlet to fail, see this example.

Next let's get started interacting with the IKANOW API.

Interacting with the API

Most methods in the API require a cookie that is granted during authentication to use.  The logical flow of using the API includes a Login call, Other API calls, and finally a Logout call.  See the examples for details on how to do each.  A cookie is only valid for 30 minutes (or whatever the system administrator has configured) from your last API call, to keep the cookie alive using the Keep Alive API call will renew the 30 minute limit.  Some methods do not require a cookie and can just be called directly.

3rd Party App Interacting with the API (CORS)

In order for 3rd party apps to negotiate CORS, we have allowed the use of API keys in 3rd party apps.  A user can set up their API key via the people manager.  Alternatively, a temporary API key can be assigned by adding the query parameter return_tmp_key=true to a auth/login call.  To aid web developers in this process, we have created a script located at API_SERVER/api/static/ikanow_js_libs/ikanow_api_auth.js.  See this example.

Example use

See these pages for examples of how to use the API.

Documentation Organization

The REST API documentation is divided into several sections:

1. Objects: documents the format of JSON objects with which API users commonly interact.  In addition to a list of fields and descriptions, these pages often contain examples that illustrate how they are used.  For example, see JSON object formats.
2. REST endpoints: Documents each REST endpoint in detail for reference purposes.  See API Reference.
3. Examples/How-Tos: Provides concise examples to perform common functionality.  See API - Examples.
4. Developer Guides: Deeper dives into how the objects and REST endpoints are used together to configure sources, query sources etc.  See Developer Guides and Tutorials.