Doit.im API Documentation

Conventions and Criteria

  • Doit.im API is a REST-based interface specification. Doit.im enables HTTP GET and Post method to communicate with Doit.im API Server (api.doit.im).
  • Doit.im API currently accepts JSON format only, so please set Content-type to JSON in request header of your POST method. For example, Content-Type:application/jsons;charset=utf-8
  • Doit.im API Server supports gzip, thus reducing/which reduces network overhead. So we suggest you add gzip in your application developers add gzip.
  • Interface Conventions of date and time format: %Y-%m-%d %H:%M:%S %z, for instance, 2010-10-10 10:10:10 +0800.

Coding

Doit.im API Server assumes that the requests are processed in UTF-8 encoding. All data will be stored in this representation.

All character type fields returned by Doit.im API Server are html escaped, so please unescape them before their displaying in clients. The following examples are the unescaped against the escaped:

    & => &
    < => &lt;
    > => &gt;
    ' => &#39;
    " => &quot;

URI

Please specify URI of the client request in the following format:

https://openapi.doit.im/:version/:resource?params

Hints:

  • version: API version number, please fill v1 now
  • resource: Resource number
  • params: other parameters related to specific interfaces
  • We strongly recommend that you encode URL parameters before the client request.

Via the following URL, you can obtain all tasks of the current user after 2010-10-10 00:00:00 

GET https://openapi.doit.im/v1/tasks?updated_after=2010-10-10

Description of return status:

Doit.im API represents the processing result of API request communication layer by HTTP Status Code. As for the processing result of business layer, please refer to the specifications on retcode and retmsg in the next session. The table below shows the possible HTTP Status Codes and their meaning.

Stauts Code Meaning
200 OK Success!
400 BAD REQUEST The request was invalid, due to request address unavailable or parameters contained not supported.
401 UNAUTHORIZED Unauthorized
403 FORBIDDEN Forbidden to access
500 INTERNAL SERVER ERROR Internal error
502 Bad Gateway Doit.im API is down or being upgraded.
503 Service Unavailable Doit.im server resources are unavailable.

Description of general returned values:

Doit.im API Server processes the request after accepting it. If there is an error during the processing, for example, the parameters in request is invalid, Doit.im API will return HTTP status code 400 as error responses, the format is shown below:

Field name Meaning Notes
retcode Business return code The business processing return code that Doit.im API Server returns, representing business processing results.
retmsg Business return information The business processing message Doit.im API Server returns.
reqdata original request parameter Data received from the request

For example:

1 
2 {
3     "reqdata":"{title\:\"with start and time\", attribute\: \"inbox\", all_day \: true, start_at \: \"2010-08-15 20:00:00\", end_at \:\"2010-08-16 21:00:00\"}",
4     "retcode":"E001",
5     "retmsg":"can not parse the request json"
6 }