The Doris API

Using your Doris data how you want, when you want.

Using the API you can integrate Doris tasks into your applications. Ideal for CMSs, CRMs or any productivity software.

Overview

The majority of Doris data and functionality are exposed via its Application Programming Interface (API). The API follows REST conventions and is implemented over standard HTTP requests. We use a "light" REST approach similar to that used by Delicious. Authentication is performed using HTTP Basic Authentication. Using the API, developers can create Doris-based applications or integrate Doris with their existing development workflow.

Contents

Authentication

Currently HTTP Basic Authentication is the only supported authentication scheme. When authenticating via Basic Auth for the first time, use your registered username and password with the get_key method to retrieve your API key. All subsequent requests should use the API key.

REST

The Doris API is loosely based on the design principles of Representational State Transfer (REST). You can change the file extension on any request to get results in the format of your choice. This document notes which formats are available for each method. Doris presently supports the following data formats: XML, JSON.

Parameters

Most API methods take a combination of required and optional parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings.

HTTP Requests

All methods use GET or POST HTTP requests, as indicated in the documentation. When requesting XML or JSON, the response is UTF-8 encoded.

HTTP Status Codes

The Doris API attempts to return appropriate HTTP status codes for every request. Here's what you should expect:

  • 200 OK: Everything went well.
  • 400 Bad Request: There was something wrong with your request, an error message will tell you what the problem was.
  • 401 Not Authorized: The authentication credentials you provided are invalid.
  • 403 Forbidden: You're attempting to access something that you're not authorised to access.
  • 404 Not Found: The resource you're requesting could not be found.
  • 500 Internal Server Error: An error occurred, an error message will tell you what the problem was.

Testing the API

You can test the API simply by using a web browser. Firefox is recommended to get decent formatting of the XML returned. Here are some requests to get you started:


Methods

Authentication

Method: check

Check authentication

URL http://beta.dorisapp.com/api/1_0/auth/check.format
Formats xml, json
Methods GET
Parameters
apikey : API string

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>ok</message>
</DRS_Success>
		

Method: get_key

Get API key. Sending HTTP Auth headers with user credentials returns API hash if recognised.

URL http://beta.dorisapp.com/api/1_0/auth/get_key.format
Formats xml, json
Methods GET

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>1a79a4d60de6718e8e5b326e338ae533</message>
</DRS_Success>
		

Tasks

Method: sync

Sync all groups and tasks with server. The complete parameter is 1 by default, which means all groups and tasks will be returned (a complete sync). If you set complete to zero only the sync operation will be called against your submitted data, and a success or failure response returned.

URL http://beta.dorisapp.com/api/1_0/tasks/sync.format
Formats xml, json
Methods POST
Parameters
apikey : API string
todo : Xml string of tasks (see view_all for format)
complete : Returns all active groups and tasks (default: 1)

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Error>
    <message>no groups supplied</message>
    <level />
    <code />
    <userinfo />
</DRS_Error>
		

Method: view_all

Display authenticated user groups with all tasks

URL http://beta.dorisapp.com/api/1_0/tasks/view_all.format
Formats xml, json, rss
Methods GET
Parameters
apikey : API string

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<array>
    <DRS_Group>
        <group_id>5</group_id>
        <group_name>first group</group_name>
        <todos>
            <DRS_Todo>
                <todo_id>21</todo_id>
                <todo_group_id>5</todo_group_id>
                <usr_id>2</usr_id>
                <description>test item</description>
                <item_order>1</item_order>
                <status>0</status>
                <date_created>2009-04-15 10:53:45</date_created>
                <last_updated>2009-07-25 10:54:16</last_updated>
                <is_today>0</is_today>
                <note />
            </DRS_Todo>
            <DRS_Todo>
                <todo_id>20</todo_id>
                <todo_group_id>5</todo_group_id>
                <usr_id>2</usr_id>
                <description>another test item</description>
                <item_order>1</item_order>
                <status>0</status>
                <date_created>2009-04-07 14:45:02</date_created>
                <last_updated>2009-07-25 10:54:24</last_updated>
                <is_today>0</is_today>
                <note />
            </DRS_Todo>
        </todos>
        <is_today>0</is_today>
    </DRS_Group>
    <DRS_Group>
        <group_id>6</group_id>
        <group_name>second group</group_name>
        <todos>
            <DRS_Todo>
                <todo_id>27</todo_id>
                <todo_group_id>6</todo_group_id>
                <usr_id>2</usr_id>
                <description>first item second group</description>
                <item_order>2</item_order>
                <status>0</status>
                <date_created>2009-07-25 10:17:02</date_created>
                <last_updated>2009-07-25 10:54:41</last_updated>
                <is_today>0</is_today>
                <note />
            </DRS_Todo>
            <DRS_Todo>
                <todo_id>26</todo_id>
                <todo_group_id>6</todo_group_id>
                <usr_id>2</usr_id>
                <description>second item second group</description>
                <item_order>2</item_order>
                <status>0</status>
                <date_created>2009-07-25 10:11:06</date_created>
                <last_updated>2009-07-25 10:54:56</last_updated>
                <is_today>0</is_today>
                <note />
            </DRS_Todo>
        </todos>
        <is_today>0</is_today>
    </DRS_Group>
</array>
		

Method: view_history

Display authenticated user completed todos

URL http://beta.dorisapp.com/api/1_0/tasks/view_history.format
Formats xml, json, rss
Methods GET
Parameters
apikey : API string
count (optional) : Number of items to fetch
from (optional): Fetch offset

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<array>
    <DRS_Todo_Cnt>
        <todo_cnt>4</todo_cnt>
    </DRS_Todo_Cnt>
    <DRS_Todo>
        <todo_id>25</todo_id>
        <todo_group_id>6</todo_group_id>
        <usr_id>2</usr_id>
        <description>and fourth</description>
        <item_order />
        <status />
        <date_created />
        <last_updated>2009-07-25 10:54:46</last_updated>
        <date>2009-07-25</date>
    </DRS_Todo>
    <DRS_Todo>
        <todo_id>24</todo_id>
        <todo_group_id>6</todo_group_id>
        <usr_id>2</usr_id>
        <description>and third</description>
        <item_order />
        <status />
        <date_created />
        <last_updated>2009-07-25 09:45:17</last_updated>
        <date>2009-07-25</date>
    </DRS_Todo>
</array>
		

Method: create

Create new task for the authenticated user. Returns the task ID.

URL http://beta.dorisapp.com/api/1_0/tasks/create.format
Formats xml, json
Methods POST
Parameters
apikey : API string
description : Task description
todo_note (optional): Task note
todo_group_id : The id of the group the task will be created in

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>29</message>
</DRS_Success>
		

Method: delete

Delete task

URL http://beta.dorisapp.com/api/1_0/tasks/delete.format
Formats xml, json
Methods POST
Parameters
apikey : API string
todo_id : The id of the task

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>1</message>
</DRS_Success>
		

Method: update

Update a task for the authenticated user

URL http://beta.dorisapp.com/api/1_0/tasks/update.format
Formats xml, json
Methods POST
Parameters
apikey : API string
todo_id : The id of the task
description : The new task description
todo_note (optional): Task note
todo_group_id (optional): The id of the group the task will be assigned to
item_order (optional): Task order
status (optional): Task status (0=incomplete, 1=complete)
last_updated (optional): Task last modification time

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>1</message>
</DRS_Success>
		

Method: update_status

Update a task status for the authenticated user

URL http://beta.dorisapp.com/api/1_0/tasks/update_status.format
Formats xml, json
Methods POST
Parameters
apikey : API string
todo_id : The id of the task
status : The new task status (0=incomplete, 1=complete)

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>1</message>
</DRS_Success>
		

Method: reorder

Reorder all the tasks for a group

URL http://beta.dorisapp.com/api/1_0/tasks/reorder.format
Formats xml, json
Methods POST
Parameters
apikey : API string
todo_ids : An array of task ids
todo_group_id : The id of the task group

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>1</message>
</DRS_Success>
		

Groups

Method: create_group

Create task group. Returns the ID of the new group.

URL http://beta.dorisapp.com/api/1_0/tasks/create_group.format
Formats xml, json
Methods POST
Parameters
apikey : API string
group_name : New group name

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>8</message>
</DRS_Success>
		

Method: update_group

Update task group

URL http://beta.dorisapp.com/api/1_0/tasks/update_group.format
Formats xml, json
Methods POST
Parameters
apikey : API string
todo_group_id : The id of the task group
group_name : New group name
item_order (optional): Task group order
status (optional): Task group status (0=visible, 1=deleted)

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>1</message>
</DRS_Success>
		

Method: reorder_groups

Reorder all the groups

URL http://beta.dorisapp.com/api/1_0/tasks/reorder_groups.format
Formats xml, json
Methods POST
Parameters
apikey : API string
todo_group_ids : An array of group ids

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<DRS_Success>
    <message>1</message>
</DRS_Success>