Kickfolio API

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.

Authentication

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

Authenticating with headers

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}"

Parameter based authentication

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

Versioning

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.

Errors

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"
    }
  ]
}

Error codes and their meaning:

You can decide how to handle errors in your code based on the HTTP status code. These are some of the status codes we support in responses, and their meaning:

• 200 OK Your request was successful.
• 201 Created Your resource was created successfully.
• 204 No Content Your resource was deleted successfully (Nothing to return, always contains an empty body).
• 400 Bad Request One of your inputs was incorrectly encoded and could not be processed.
• 401 Unauthorized You need to provide authentication credentials, or your credentials were rejected.
• 422 Record is invalid. One of the values you supplied for an attribute did not pass validation. Please retry with another value.
• 500 Internal Server Error We fucked up. We've been notified of the issue and our engineering team will fix the issue shortly. Please try again in a few hours.

Understanding the documentation

Our API makes extensive use of HTTP verbs to define endpoints, and instruct the server as to the nature of your request.

The HTTP verbs we support are:

• GET
• POST
• PUT
• DELETE

Each documented endpoint is written in a format similar to the following:

GET /api/resource/:identifier
PUT /api/apps/123

To access this these resources using the curl command line utility you would run this command:

$ curl https://kickfolio.com/api/apps/123 -X PUT -d '{"app" : {"name" : "New App Name"}}'

The :identifier component is a variable component which you should replace with the record identifer you need.

You can safely swap and replace any resource name mentioned in the docs with a another and access it in the same way. For example, all update actions are done using the PUT verb, and all creation actions are done using the POST verb.

POST /api/apps

Throughout the documentation we make reference to resources which may be nested under other resources, for example:

GET /api/apps/:app_id/versions/:id

In this case you can safely swap app_id with either the App public_key or App UUID formatted ID. For brevity this may not be mentioned in the documentation for every resource.