Our API allows you to create and manage your Apps, including uploading new Versions, removing Versions, and commenting on Versions.

All responses are in JSON format, and the URL structure generally tries to follow RFC-2616.

All requests are authenticated using your authentication token, which is found on your account page when logged into the Kickfolio dashboard.

There are two ways to authenticate:

1. Supplying an Authorization header (preferred)
2. Supplying the auth_token parameter

Header authentication follows the typical HTTP Authorization scheme of providing a BASE64 encoded hash to your authentication credentials. In this case the credentials are simply your authentication_token.

To generate the correct header simply apply a Base64 strict encoding (no linefeeds) to your authentication_token and send it as HTTP Basic auth: Authorization: Basic MY_BASE64_ENCODED_TOKEN. If your client library insists on supplying a password for sending basic auth, you can use X, which will be ignored on our end.

Ruby example:

encoded_token = Base64.strict_encode64(authentication_token)
request.header('Authorization', "Basic #{encoded_token}"

The second option for authentication is supplying the auth_token parameter on the end of your query.

Here's an example:

curl http://kickfolio.com/api/apps?auth_token=MY_RAW_AUTH_TOKEN

All API requests are subject to versioning, where the current version is always the latest version. It is strongly advised that you specify a specific version when requesting API resources. This is done by supplying an HTTP Accept e.g.

curl -H 'Accept: application/vnd.kickfolio.v1' http://kickfolio.com/api/apps

The versioning format is application/vnd.kickfolio.v1 where v1 is the version idenifier. At the time of writing the only version available is v1, however v2 is planned.

If you incorrectly access a resource the API will respond with an HTTP status code in the 4xx space or 5xx space depending on the cause. The body of the response will contain a JSON formatted error message based on the following schema:

{
  "message": "STRING - A human readable exmplanation of the problem",
  "code": "STRING - a unique string identifying the problem e.g. record_invalid",
  "errors": [ // Optional - only on record_invalid
    {
      "field" : "The property which was invalid",
      "resource" : "The name of the invalid resource",
      "message" : "The reason the field is invalid"
    }
  ]
}

• GET /api/apps returns a collection of Apps.

• ids Optional Array: An array of IDs to filter the collection. Designed to work with Ember Data bulk loading.

Status: 200 OK

{
  "apps": [
    {
      "id": "ae42f072-3f1a-11e2-92da-1231394268a3",
      "user_id": "57198bee-3f1a-11e2-92da-1231394268a3",
      "name": "Kickfolio",
      "public_key": "ABCD123",
      "bundle": "com.kickfolio.app",
      "default_to_landscape": false,
      "icon": "https://www.filepicker.io/api/file/SECRET",
      "device_type": "iPhone",
      "created_at": "2012-12-05T20:30:59Z",
      "updated_at": "2012-12-05T20:31:09Z",
      "version_ids": [
        "ae45868e-3f1a-11e2-92da-1231394268a3"
      ]
    }
  ]
}

• GET /api/apps/:id returns a single App record.
• GET /api/apps/:public_key returns a single App record.

• id Required 128bit UUID: App ID. Only required if public_key is not used.
• public_key Optional String: App public key, used in place of an id for short urls.

Status: 200 OK

{
  "app": {
    "id": "ae42f072-3f1a-11e2-92da-1231394268a3",
    "user_id": "57198bee-3f1a-11e2-92da-1231394268a3",
    "name": "Kickfolio",
    "public_key": "ABCD123",
    "bundle": "com.kickfolio.app",
    "default_to_landscape": false,
    "icon": "https://www.filepicker.io/api/file/SECRET",
    "device_type": "iPhone",
    "created_at": "2012-12-05T20:30:59Z",
    "updated_at": "2012-12-05T20:31:09Z",
    "version_ids": [
      "ae45868e-3f1a-11e2-92da-1231394268a3"
    ]
  }
}

• POST /api/apps creates a new App, returning the new record.

• name Required String: The name of your App.

Status: 201 Created

{
  "app": {
    "id": "ae42f072-3f1a-11e2-92da-1231394268a3",
    "user_id": "57198bee-3f1a-11e2-92da-1231394268a3",
    "name": "Kickfolio",
    "public_key": "ABCD123",
    "bundle": "com.kickfolio.app",
    "default_to_landscape": false,
    "icon": "https://www.filepicker.io/api/file/SECRET",
    "device_type": "iPhone",
    "created_at": "2012-12-05T20:30:59Z",
    "updated_at": "2012-12-05T20:31:09Z",
    "version_ids": [
      "ae45868e-3f1a-11e2-92da-1231394268a3"
    ]
  }
}

• PUT /api/apps/:id updates attributes of an existing app, returning result.
• PUT /api/apps/:public_key updates attributes of an existing app, returning result.

• name Required String: The name of your App.

Status: 200 OK

{
  "app": {
    "id": "ae42f072-3f1a-11e2-92da-1231394268a3",
    "user_id": "57198bee-3f1a-11e2-92da-1231394268a3",
    "name": "Kickfolio",
    "public_key": "ABCD123",
    "bundle": "com.kickfolio.app",
    "default_to_landscape": false,
    "icon": "https://www.filepicker.io/api/file/SECRET",
    "device_type": "iPhone",
    "created_at": "2012-12-05T20:30:59Z",
    "updated_at": "2013-1-20T18:31:09Z",
    "version_ids": [
      "ae45868e-3f1a-11e2-92da-1231394268a3"
    ]
  }
}

• DELETE /api/apps/:id deletes your App, returning nothing.
• DELETE /api/apps/:public_key deletes your App, returning nothing.

Nothing

Status: 204 No Content