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:
- Supplying an
Authorization
header (preferred) - 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"
}
]
}
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.
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.