Doit.im API 文档

约定和标准

Doit.im API是采用REST基础的接口规范。所有的API都是通过HTTP GET、POST方法向Doit.im API Server(api.doit.im)发送请求实现的。
对于 POST方法, Doit.im API 目前接受JSON的数据类型。在使用POST方法时，请将 Contecnt-Type 指定为json. 例如: Content-Type: application/json; charset=utf-8’
Doit.im API Server 支持gzip，这样能降低网络的开销，建议开发者在应用中加入gzip。
接口中日期和时间的约定: %Y-%m-%d %H:%M:%S %z 如: 2010-10-10 10:10:10 +0800

编码

Doit.im API Server 假定客户端的请求均为UTF-8编码格式进行处理。所有的数据都将以UTF-8编码后存储。

Doit.im API Server 返回的字符型字段均进行了html转义, 客户端在显示这些字段时进行反转义。以下为被转义的字符对照:

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

URI

客户端请求URI按如下格式:

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

说明:

version: API版本号, 目前填 v1
resource: 资源名称
params: 其他与具体接口相关的参数
我们强烈建议客户端在请求前对URL参数进行URL编码

下面的例子获取了当前用户2010-10-10 00:00:00 以后的所有任务

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

返回状态说明

Doit.im API 通过HTTP Status Code来说明 API 请求通讯层的处理结果.对于业务层的处理结果见下节中retcode和retmsg的说明. 下面的表格中展示了可能的HTTP Status Code以及其含义

状态码	含义
200 OK	请求处理成功
400 BAD REQUEST	请求的地址不存在或者包含不支持的参数
401 UNAUTHORIZED	未授权
403 FORBIDDEN	被禁止访问.
500 INTERNAL SERVER ERROR	内部错误
502 Bad Gateway	API关闭或正在升级
503 Service Unavailable	服务端资源不可用

通用返回值说明

Doit.im API Server接受客户端请求后进行处理, 如果在处理过程中存在错误,如客户端上传的参数不合法, Doit.im API Server将返回HTTP状态码400, 相应的错误回应,格式如下:

字段名	意义	备注
retcode	业务返回码	Doit.im API Server 返回的业务处理返回信息码, 用来代表各种业务的处理结果。
retmsg	业务返回信息	Doit.im API Server 返回的业务处理返回信息。
reqdata	原请求参数信息	服务器接收到的请求信息

如:

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 }