Login Deutsch

Developers welcome! The mite.api is looking forward to your precious hacking. Have a look at the detailed documentation to kick-start your coding.

Overview

Introduction

Our mite.api is designed around the principles of REST. It has predictable, resource oriented URIs that you interact with using HTTP verbs, and we use HTTP response codes to indicate API errors.

All API access is over HTTPS, and accessed from an account specific domain:

:account_name.mite.yo.lk

We'll use demo as our account name and subdomain from here on; please replace it with the accurate subdomain of your own account.

Supported formats

We support JSON and XML to send and receive data. We generally prefer and recommend to use JSON: it is more compact on the wire and our servers are able to generate it much faster.

Specify the format as a suffix to the URL; the HTTP header Accept is not supported:

https://demo.mite.yo.lk/users.json
https://demo.mite.yo.lk/users.xml

All dates and timestamps in JSON and XML are represented in ISO 8601 format:

YYYY-MM-DD
YYYY-MM-DDTHH:MM:SSZ

Timestamps always reflect the time zone of your account.

HTTP verbs

You can use the following HTTP verbs to interact with the mite.api:

HEAD Can be issued against any resource to get just the HTTP header info without the body.
GET Used for retrieving resources.
POST Used for creating resources.
PATCH Used for updating resources with partial data. PATCH is a relatively new and uncommon HTTP verb, so resource endpoints also accept PUT requests for backward compatibility.
DELETE Used for deleting resources.

Tools

With a regular browser, you can only read resources. Because Firefox is able to display XML data inline, it is perfect for that task. To display JSON inline we recommend to install the add-on JSONView.

To use all features of the mite.api, we recommend a command line tool such as cURL or the more "human-friendly" HTTPie.

Not familiar with the command line? You might want to have a look at the Firefox add-on RESTClient, or the Google Chrome extension Rest Console.

Authentication

You won't have to setup a special user to use the API. Every existing mite.user can activate the API in his or her user settings: Please click on your user name in the upper right-hand corner of the mite.interface. Check the corresponding checkbox there, and save this edit. You'll then get your personal API key by clicking the corresponding link.

There are two ways to authenticate: You can either use your regular user credentials that you specify when logging in with your browser. Or you can use your personal API key.

Important: For safety reasons, we strongly recommend to use the API key whenever possible. Your password should only be used with simple throw-away scripts and similar.

With e-mail and password

Enter your regular user credentials (email and password) per HTTP basic. A pretty simple example using curl:

curl -u you@mail.com:YOUR_PASSWORD \
https://demo.mite.yo.lk/projects.json
curl -u you@mail.com:YOUR_PASSWORD \
https://demo.mite.yo.lk/projects.xml

Please replace the subdomain 'demo' with the accurate subdomain of your account throughout the following examples.

With the API key

To authenticate using your API key, you can either send it as HTTP header X-MiteApiKey:

curl -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/projects.json
curl -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/projects.xml

or for GET-requests as paramter api_key:

curl https://demo.mite.yo.lk/projects.json?api_key=YOUR_API_KEY
curl https://demo.mite.yo.lk/projects.xml?api_key=YOUR_API_KEY

Set your user agent

Please set the User-Agent HTTP header for all of your requests. The header should include the name of your application or script, and a link or e-mail address, so we can get in touch in case there are any problems. Bonus points for including the used library including its version number. Here's an example:

User-Agent: mite.app/v1.1 (https://github.com/yolk); mite-rb/0.5.3

This may become a requirement in the future. To design your agent future-proof, please set the user-agent header in each and every client.

Reading resources

By using the HTTP verb GET, resources can be read either in list form or as a single resource.

Single resource

To read a single resource, the URL has to be composed of the path of the resource and the id of the resource:

curl -v -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/services/1.json
curl -v -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/services/1.xml

List of resources

A list can be read by using the path of the resources:

curl -v -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/services.json
curl -v -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/services.xml

If your request was interpreted successfully, you will receive a HTTP status code of 200 OK as well as the requested resource in JSONXML format.

Writing resources

By using the HTTP methods POST, PATCH and DELETE, data can be written in JSON or in XML.

Please note: You MUST set the format used in your request body for every writing request with the HTTP header Content-Type. In case of JSONXML set the header to application/jsonxml.

Create a resource

curl -v -X POST \
-H 'X-MiteApiKey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"service":{"name":"Coding"}}' \
https://demo.mite.yo.lk/services.json
curl -v -X POST \
-H 'X-MiteApiKey: YOUR_API_KEY' \
-H 'Content-Type: application/xml' \
-d '<service><name>Coding</name></service>' \
https://demo.mite.yo.lk/services.xml

This request will create a new resource by using POST – in this example a new service named 'Coding'. If your request was interpreted successfully, you will receive a status code of 201 Created, a Location header pointing to the resource, as well as the complete resource in the response body.

Update a resource

A resource that already exists can be edited by using the PATCH method:

curl -v -X PATCH \
-H 'X-MiteApiKey: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"service":{"name":"Quality assurance"}}' \
https://demo.mite.yo.lk/services/1.json
curl -v -X PATCH \
-H 'X-MiteApiKey: YOUR_API_KEY' \
-H 'Content-Type: application/xml' \
-d '<service><name>Quality assurance</name></service>' \
https://demo.mite.yo.lk/services/1.xml

If the update was successful, you will receive a status code of 200 OK.

Delete a resource

You can delete a resource in a similar way by using the DELETE method. You won't have to send any data in the request body of course – this also means you can skip the Content-Type-header:

curl -v -X DELETE -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/services/1.json
curl -v -X DELETE -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.yo.lk/services/1.xml

If the resource was deleted successfully, you will receive a status code of 200 OK as well.

HTTP status codes

Here, you'll find a list of all HTTP status codes the mite.api returns, and how to interpret them. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a condition failed, etc.), and codes in the 5xx range indicate an error with our servers.

200 OK Everything worked as expected.
201 Created Resource was succesfully created.
400 Bad Request Often a malformatted request body.
401 Unauthorized Missing or wrong API key.
403 Forbidden The authenticated user is not allowed to perform this request. Maybe the user has only the role of a time tracker?
404 Not Found Resource was not found. Requests that require a special role will return 404 Not Found, instead of 403 Forbidden, in some places. This is to prevent the accidental leakage of sensible information to unauthorized users.
406 Not Acceptable The requested format is not supported. Please use JSON or XML instead.
422 Unprocessable Entity Often missing required attributes.
423 Locked You are trying to modify a locked time entry.
500, 502, 503 Server Error Something went wrong on our end. Try to repeat the request later or file a bug if the error persists.

Client errors

In most cases you will be able to interpret the cause of an error from the returned HTTP status code. For further details the mite.api will additionally return an error resource in the response body as well. Some examples:

Using a wrong and non-existing account name for the domain in the request:

Status: 404 Not Found
{
   {
     "error": "Whoops! We couldn't find your account 'unknown'."
   }
}
Status: 404 Not Found
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Whoops! We couldn't find your account 'unknown'.</error>
</errors>

Using the wrong or no authentication credentials:

Status: 401 Unauthorized
{
   {
     "error": "Access denied. Please check your credentials."
   }
}
Status: 401 Unauthorized
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Access denied. Please check your credentials.</error>
</errors>

Missing a required attribute when updating or creating a resource:

Status: 422 Unprocessable Entity
{
   {
     "error": "Please name your project."
   }
}
Status: 422 Unprocessable Entity
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Please name your project.</error>
</errors>

Requesting an already deleted resource:

Status: 404 Not Found
{
   {
     "error": "The record does not exist."
   }
}
Status: 404 Not Found
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>The record does not exist.</error>
</errors>

Using malformatted JSONXML in the request body:

Status: 400 Bad Request
{
   {
     "error": "Your submitted data is not valid JSON: 795: unexpected token at '{\"service: {}}'"
   }
}
Status: 400 Bad Request
<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Your submitted data is not valid XML: Start tag expected, '<' not found</error>
</errors>

Conditional requests

Most responses return an ETag HTTP header. You can use the value of these headers to make subsequent requests to the same resource using the If-None-Match header. If the resource has not changed, the server will return a 304 Not Modified. This can be especially useful when you need to repeatedly access huge lists of resources.

Example

$ curl -i https://demo.mite.yo.lk/services/1.json
HTTP/1.1 200 OK
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

$ curl -i https://demo.mite.yo.lk/services/1.json \
-H 'If-None-Match: W/"883112cb2ba78a99e4e562de2a6dd305"'
HTTP/1.1 304 Not Modified
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}
$ curl -i https://demo.mite.yo.lk/services/1.xml
HTTP/1.1 200 OK
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

$ curl -i https://demo.mite.yo.lk/services/1.xml \
-H 'If-None-Match: W/"883112cb2ba78a99e4e562de2a6dd305"'
HTTP/1.1 304 Not Modified
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

Libraries

Ruby mite.rb Official Ruby library
PHP MiteEleven by SysEleven
PHP mite.php by Thomas Klein
PHP Mitey by Stefan Pasch
Node.js mite-api by Marcel Meyer
Objective-C CocoaMite by Heiko Dreyer
.NET mite.net by Christoph Keller
Java JMite by Oliver Gierke

Open source examples

Ruby mite.cmd A command line interface for mite.
By Lukas Rieder
Ruby git2mite Writes git commit messages to mite.
By Alexander Lang
Python Git-Hooks Adds hooks to use mite with any git repository.
By Thomas Spycher
Ruby Mantis2mite Integrates mite with the project manager Redmine.
By Thomas Klein
Python Trac2mite Integrates mite with the bug tracker Trac.
By Thomas Klein
PHP Mantis2mite Integrates mite with the bug tracker Mantis.
By Thomas Klein
.NET TrelloMite Integrates mite with the ToDo manager Trello.
By Hannes Sachsenhofer
Java mite4java Helps with reporting and Excel export.
By Simon Martinelli
Ruby CoReMite A console reporter.
By Christopher de Bruin