• Introduction
• Supported formats
• HTTP verbs
• Tools
• Authentication
• Set your user agent
• Reading resources
• Writing resources
• HTTP status codes
• Client errors
• Conditional requests
• Libraries
• Open source examples

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:

https://{account_name}.mite.de

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.de/users.json

https://demo.mite.de/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:

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 [email protected]:YOUR_PASSWORD \
https://demo.mite.de/projects.json

curl -u [email protected]:YOUR_PASSWORD \
https://demo.mite.de/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.de/projects.json

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

or for GET-requests as paramter api_key:

curl https://demo.mite.de/projects.json?api_key=YOUR_API_KEY

curl https://demo.mite.de/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.de/services/1.json

curl -v -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.de/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.de/services.json

curl -v -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.de/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.de/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.de/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.de/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.de/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.de/services/1.json

curl -v -X DELETE -H 'X-MiteApiKey: YOUR_API_KEY' \
https://demo.mite.de/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.

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:

{
   "error": "Whoops! We couldn't find your account 'unknown'."
}

<?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:

{
   "error": "Access denied. Please check your credentials."
}

<?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:

{
   "error": "Please name your project."
}

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>Please name your project.</error>
</errors>

Requesting an already deleted resource:

{
   "error": "The record does not exist."
}

<?xml version="1.0" encoding="UTF-8"?>
<errors>
  <error>The record does not exist.</error>
</errors>

Using malformatted JSONXML in the request body:

{
   "error": "Your submitted data is not valid JSON: 795: unexpected token at '{\"service: {}}'"
}

<?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.de/services/1.json
HTTP/1.1 200 OK
ETag: W/"883112cb2ba78a99e4e562de2a6dd305"
{...}

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

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

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

Libraries

Open source examples