Skip to main content

Introduction

General information#

The Kiliaro API is a fully RESTful JSON API. It works with objects rather than function calls. For instance, if one wishes to change the e-mail of a user, there is no setEmail function in the API, instead a list of changes are POSTed to the user object:

Request:

$ curl -X POST "https://api1.kiliaro.com/users/57ab2faf0239407cc558338b00000001?apikey=t-95681817-b644-4874-a027-08e045f82ba2" \  -H "Content-Type: application/json"  -d '{"email": "batman@gotham.org"}'

Response:

{  "account_type": "premium",  "quota_id": "57ab2faf0239407cc558338b00000001",  "created_at": "2015-04-13T21:05:51Z",  "email": "batman@gotham.org",  "name": "Bruce Wayne",  "id": "57ab2faf0239407cc558338b00000001"}

User Authentication#

Standard OAuth2 is supported at https://auth.kiliaro.com/

Accepted scopes are:

  • user
  • images

Authorization#

API requests can be authorized in two ways:

  • When accessing the API on behalf of a user. In this case, the user should authenticate through OAuth2, and then use the returned access token when requesting the API.
  • When accessing the API through another system. In this case, an API key will be given out by Kiliaro which is not tied to any specific user.

The API endpoint to use is https://api1.kiliaro.com. The access token for each request should be sent along in one of two ways:

  • Either as a query parameter called access_token, for instance https://api.kiliaro.com/my/media?access_token=t-9de58d65-68ec-417f-92d5-3fadb29b08aa
  • Or in the Authorization HTTP header with a Bearer type, for instance: Authorization: Bearer t-9de58d65-68ec-417f-92d5-3fadb29b08aa.

Data types#

The API uses standard data types in JSON such as numbers, strings, booleans etc.

The only special case in the API is our timestamp data type we use for dates and times. It should be a string containing a timestamp formatted according to RFC3339, such as 2017-03-29T12:29:35+02:00. Some parts of the API also makes use of timestamps where the timezone is not known, for instance when extracting the date when a JPEG picture was taken from its EXIF metadata, since EXIF has no support for timezones. These dates will be expressed with a local offset set to -00:00 as specified in RFC3339 section 4.3.

Errors#

Errors are reported through HTTP codes. Non-successfull requests will return a non-2XX HTTP code, most commonly 400. A desription of the error will be sent along in a JSON body. For instance:

POST /my/directories/54b3dff608002711dff7117700000003
{  "trashed": "not a boolean"}

Responds:

HTTP/1.1 400 Bad RequestContent-Type: application/json
{  "http_code": 400,  "field_errors": {    "trashed": "must be of type boolean"  },  "error": "Invalid values for JSON fields"}

General examples#

The following are examples of API requests using an API key given out by Kiliaro:

Looking up a user#

The following example shows how to load a user based on e-mail.

GET /users;email=andreas@kiliaro.com?apikey=t-95681817-b644-4874-a027-08e045f82ba2 HTTP/1.1Host: api1.kiliaro.com
HTTP/1.1 200 OKContent-Type: application/json
[  {    "account_type": "premium",    "quota_id": "57ab2faf0239407cc558338b00000001",    "created_at": "2015-04-13T21:05:51Z",    "email": "andreas@kiliaro.com",    "name": "andreas@kiliaro.com",    "id": "57ab2faf0239407cc558338b00000001"  }]