Documentation API 1.1

Overview

You will know (almost) everything about the API and how to use it, so be happy!
Data are sent and received as JSON.

The API is available under labs.devenet.eu/moods/api/v1.

To register an account and get your API credentials, please make a request.

Errors

If the API is unable to respond to your request, an error (based on HTTP protocol) will be returned.

{
    "error": 400,
    "message": "Bad Request"
}

The following client errors can be returned:

400	Bad Request
401	Unauthorized
422	Unprocessable entity

The following server errors can be returned:

501	Not Implemented
503	Service Unavailable

The message field give you often a better explaination, especially when it's a 422 error.

Version

GET /version

You can get the current version for the API and the MoodPicker application.

{"api_version":"1.1.0", "moodpicker_version":"1.2.0"}

Authentification

Get a token

POST /token {"api_key": ":api_key", "api_token": ":api_token"}

Authentification is required to post data through a generated token from the API. To get open data, such as moods, authentification is not required.
The request, with your credentials :api_key and :api_token, returns a token you have to use in your next POST request, and the timestamp before expiration.

{"token": "token_to_use", "expire": 1410962303}

Test your credentials

POST /authentification {"api_key": ":api_key", "api_token": ":api_token"}

In order to test if the credentials are valid but without asking for a token, you can have an answer using this method.
It will return a 401 error or the following JSON.

{"authentification": true}

Moods translation

GET /translation

Returned values

{
    "translation": {
        "GOOD": 1,
        "BAD": -1
    }
}

Get mood’s review

Returned values

{
    "date": "2014-09-15",
    "moods_count": 42,
    "moods": [
        {
            "mood": -1,
            "timestamp": 1406748783
        },
        …
    ]
}

This is an example of mood’s review given by the API.
Note that the date field could be shorter, depending on what is asked.

Day’s review

GET /day 
GET /day/:date

The :date parameter should be formatted like YYYY-MM-DD.
If the parameter :date is omitted, the server will return the mood’s review for the server current day.

YYYY

Year on 4 digits

MM

Month on 2 digits with leading zero

DD

Day on 2 digits with leading zero

Month’s review

GET /month 
GET /month/:date

The :date parameter should be formatted like YYYY-MM.
If the parameter :date is omitted, the server will return the mood’s review for the server current month.

YYYY

Year on 4 digits

MM

Month on 2 digits with leading zero

Year’s review

GET /year 
GET /year/:date

The :date parameter should be formatted like YYYY.
If the parameter :date is omitted, the server will return the mood’s review for the server current day.

YYYY

Year on 4 digits

Submit a mood

POST /submit {"mood": :mood}

The parameter :mood is the current mood, and is one of the numeric values got from /translation.
If everything is OK, the API returns the mood you have submitted.

{"mood": 1, "timestamp": 1406748783}