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.

Authentication
REST
Parameters
HTTP Requests
HTTP Status Codes
Testing the API
Methods

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>

Doris

The Doris API

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

Overview

Contents

Authentication

REST

Parameters

HTTP Requests

HTTP Status Codes

Testing the API

Methods

Authentication

Method: check

Method: get_key

Tasks

Method: sync

Method: view_all

Method: view_history

Method: create

Method: delete

Method: update

Method: update_status

Method: reorder

Groups

Method: create_group

Method: update_group

Method: reorder_groups