Hello developers!

Here is a quick tutorial on 42goals API. The two keywords you should know are: REST and OAuth, as we use these two standards in our API design. In general, your application will send a simple HTTP request and obtain an XML or JSON response.

Getting started

In order to use the API, you need to register your application. For that you will need an account at 42goals.com. Simply login your account and go to the applications page. You will need to come up with an application name and a description. They will be used to tell users about your app. In return you will receive two tokens: app key and secret. Both 32-character-length hex strings that are used in OAuth workflow. Keep them in a safe place, especially, the secret string. If you are not familiar with OAuth a good place to start is here: http://hueniverse.com/oauth/. It is also a good idea to use a ready-made library for your programming language and environment: http://oauth.net/code/.

Authorization and authentication

We use OAuth for authentication of apps and managing access to users' data. Once you have obtained tokens for your app, here are the access points for OAuth workflow:

  • Get request token: http://api.42goals.com/v1/oauth/request_token/
  • Authorize token: http://42goals.com/settings/authorize/$REQUEST_TOKEN/
  • Get access token: http://api.42goals.com/v1/oauth/access_token/

Requests and responses

42goals API is designed in REST-style, i.e. you will make HTTP requests and we give you a response in XML or JSON formats. GET requests are used to retrieve data, POST for adding new data, PUT for modifying existing data, and DELETE will erase data. For example:

  • GET http://api.42goals.com/v1/goals/1/ — returns information of the goal with ID=1
  • POST http://api.42goals.com/v1/goals/ — adds a new goal
  • PUT http://api.42goals.com/v1/goals/1/ — edits the goal with ID=1
  • DELETE http://api.42goals.com/v1/goals/1/ — deletes the goal with ID=1

By default, all the responses are given in XML format. You may pass an HTTP header “Accept: text/json” to set the JSON format.

Resources

Goals

Goal is a user's objective for which he tracks the data. A goal has the following fields:

Name Type (max-length) Description
id integer a unique identification number of a goal
type one of: "boolean", "numeric", "counter" type of the data stored for the goal
title string (255) goal's name
text string (65536) goal's description
position integer goal's order in the list of goals, used for sorting goals
icon_item integer icon's ID for counter goals
icon_true integer icon's ID for boolean goals to represent true value
icon_false integer icon's ID for boolean goals to represent false value
unit string (32) goal's unit of measurements
prepend "yes" or "no" whether the unit of measurements should be before the value, such as for "$100"
aggregate one of: "none", "sum", "avg", "min", "max" goal's aggregate function

Request: GET http://api.42goals.com/v1/goals/
Description: lists all user's goals
Parameters: none
Response:

<?xml version="1.0"?>
<root>
    <goal>
        <id>1</id>
        <type>boolean</type>
        <title>Productivity</title>
        <text>Productivity is a measure of output from a production process
        </text>
        <position>1</position>
        <icon_item>0</icon_item>
        <icon_true>19</icon_true>
        <icon_false>20</icon_false>
        <unit></unit>
        <prepend>no</prepend>
        <aggregate>none</aggregate>
    </goal>
    <goal>
        <id>2</id>
        <title>Jogging</title>
        <type>numeric</type>
        <text>Jogging every day helps me to wake up and stay focused all day long</text>
        <icon_item>0</icon_item>
        <icon_true>0</icon_true>
        <icon_false>0</icon_false>
        <position>2</position>
        <unit>m</unit>
        <prepend>no</prepend>
        <aggregate>sum</aggregate>
    </goal>
</root>

Request: POST http://api.42goals.com/v1/goals/
Description: add a new goal
Parameters: goal info (see the table above)
Examples of the POST body:
1. type=numeric & title=Jogging & unit=km
2. type=boolean & title=Productivity & icon_true=1 & icon_false=1
3. type=counter & title=Coffee & icon_item=3

Response:

<?xml version="1.0"?>
<root>
    <goal>
        <id>1</id>
        <type>numeric</type>
        <title>Jogging</title>
        <unit>km</text>
    </goal>
</root>

Request: GET http://api.42goals.com/v1/goals/$GOAL_ID/
Description: get info of the goal with ID = $goal_id
Parameters: none
Response:

<?xml version="1.0"?>
<root>
    <goal>
        <id>1</id>
        <type>boolean</type>
        <title>Productivity</title>
        <text>Productivity is a measure of output from a production process
        </text>
        <position>1</position>
        <icon_item>0</icon_item>
        <icon_true>19</icon_true>
        <icon_false>20</icon_false>
        <unit></unit>
        <prepend>no</prepend>
        <aggregate>none</aggregate>
    </goal>
</root>

Request: PUT http://api.42goals.com/v1/goals/$GOAL_ID/
Description: edit goal with ID = $goal_id
Parameters: goal info (see the table above)
Example of the PUT body:
title=Jogging & text=Jogging is good

Response:

<?xml version="1.0"?>
<root>
    <goal>
        <id>1</id>
        <title>Jogging</title>
        <text>Jogging is good</text>
    </goal>
</root>

Request: DELETE http://api.42goals.com/v1/goals/$GOAL_ID/
Description: delete goal with ID = $goal_id
Parameters: none
Response:

<?xml version="1.0"?>
<root>
    <ok>ok</ok>
</root>

Icons

Name Type (max-length) Description
id integer icon's ID
src string (255) URL of icon's image
editable 1 or 0 whether the current user can modify the icon i.e. has to be its owner

Request: GET http://api.42goals.com/v1/icons/
Description: get all icons available to the current user
Parameters: none
Response:

<?xml version="1.0"?>
<root>
    <icon>
        <id>1</id>
        <src>http://42goals.com/public/img/icons/admin/1.png</src>
        <editable>0</editable>
    </icon>
    <icon>
        <id>2</id>
        <src>http://42goals.com/public/img/icons/admin/2.png</src>
        <editable>0</editable>
    </icon>
    <icon>
        <id>3</id>
        <src>http://42goals.com/public/img/icons/alex/3.png</src>
        <editable>1</editable>
    </icon>
</root>

Request: POST http://api.42goals.com/v1/icons/
Description: add a new icon
Parameters: image content encoded with base64 algorithm and image name
ex: image=iVBORw0KGgoAAAANSU...RK5CYII= & name=icon.png
Response:

<?xml version="1.0"?>
<root>
    <icon>
        <id>1</id>
        <src>http://42goals.com/public/img/icons/admin/1.png</src>
    </icon>
</root>

Request: GET http://api.42goals.com/v1/icons/$ICON_ID/
Description: get info of the icon with ID = 1
Parameters: none
Response:

<?xml version="1.0"?>
<root>
    <icon>
        <id>1</id>
        <src>http://42goals.com/public/img/icons/admin/1.png</src>
        <editable>0</editable>
    </icon>
</root>

Request: DELETE http://api.42goals.com/v1/icons/$ICON_ID/
Description: delete icon with ID = 1
Parameters: none
Response:

<?xml version="1.0"?>
<root>
    <ok>ok</ok>
</root>

Data

Name Type (max-length) Description
goal integer goal's ID
date date (YYYY-MM-DD) day of the log
value integer or double value
text string (65536) value comment

The date format in the API requests is as follows: ddmmmyy, where dd - is numerical representation or the date, mmm - the first three letters of the month and yy - the last two digits of the year, e.g.: 1aug10 = August 1, 2010.

Request: GET http://api.42goals.com/v1/data/$GOAL_ID/$DATE/
Description: get data for goal with ID = $goal_id on date = $date
Parameters: none
Response:

ex: GET http://api.42goals.com/v1/data/1/1aug10/
<?xml version="1.0"?>
<root>
    <date>2010-08-01</date>
    <goal>1</goal>
    <data>
        <value>1</value>
        <text></text>
    </data>
</root>

Request: POST http://api.42goals.com/v1/data/$GOAL_ID/$DATE/
Description: set data for goal with ID = $goal_id on date = $date
Parameters: value and/or text (see the table above)
ex: value=1 & text=Some comment
Response:

ex: POST http://api.42goals.com/v1/data/1/1aug10/
<?xml version="1.0"?>
<root>
    <date>2010-08-01</date>
    <goal>1</goal>
    <data>
        <value>1</value>
        <text></text>
    </data>
</root>

Request: GET http://api.42goals.com/v1/data/$GOAL_ID/$DATE1-$DATE2/
Description: get data for goal with ID = $goal_id on a period between $date1 and $date2 inclusively
Parameters: none
Response:

ex: GET http://api.42goals.com/v1/data/1/1aug10-3aug10/
<?xml version="1.0"?>
<root>
    <date>2010-08-01--2008-08-03</date>
    <goal>1</goal>
    <data>
        <date>2010-08-01</date>
        <value>1</value>
        <text>some comment</text>
    </data>
    <data>
        <date>2010-08-02</date>
        <value>2</value>
        <text></text>
    </data>
    <data>
        <date>2010-08-03</date>
        <value>3</value>
        <text></text>
    </data>
</root>

Request: GET http://api.42goals.com/v1/data/$DATE/
Description: get data for all user's goals on date = $date
Parameters: none
Response:

ex: GET http://api.42goals.com/v1/data/1aug10/
<?xml version="1.0"?>
<root>
    <date>2010-08-01</date>
    <data>
        <goal>1</goal>
        <value>1</value>
        <text>some comment</text>
    </data>
    <data>
        <goal>2</goal>
        <value>2</value>
        <text></text>
    </data>
    <data>
        <goal>3</goal>
        <value>3</value>
        <text></text>
    </data>
</root>

Request: GET http://api.42goals.com/v1/data/$DATE1-$DATE2/
Description: get data for all user's goals on a period between $date1 and $date2
Parameters: none
Response:

ex: GET http://api.42goals.com/v1/data/1aug10-3aug10/
<?xml version="1.0"?>
<root>
    <date>2010-08-01--2008-08-02</date>
    <data>
        <date>2010-08-01</date>
        <goal>1</goal>
        <value>1</value>
        <text>some comment</text>
    </data>
    <data>
        <date>2010-08-01</date>
        <goal>2</goal>
        <value>2</value>
        <text>some other comment</text>
    </data>
    <data>
        <date>2010-08-02</date>
        <goal>1</goal>
        <value>3</value>
        <text></text>
    </data>
    <data>
        <date>2010-08-02</date>
        <goal>2</goal>
        <value>4</value>
        <text></text>
    </data>
</root>

Me

This request can be used to retrive user's information such as name, login and email.

Request: GET http://api.42goals.com/v1/me/
Description: get information about the current user
Parameters: none
Response:

<?xml version="1.0"?>
<root>
    <user>
        <id>1</id>
        <login>alex</login>
        <name>Alex Pak</name>
        <email>irokez@gmail.com</email>
    </user>
</root>