申请

发送邮件给 vip@snoworange.com 提供以下信息:

  1. 应用使用在 中国区(http://doitim.com) 还是 国际区(http://doit.im)
  2. 开发者的doit 用户名和邮箱
  3. 应用名称
  4. 应用开发者/机构显示名称
  5. 应用描述
  6. redirect_uri (如: http://myapp.com/callback)

审批

审批后会以邮件的方式将信息发送给申请人。

使用

获取用户授权

HTTP GET https://i.doitim.com/oauth

输入参数

client_id
redirect_uri
response_type=code

开发者在应用内打开浏览器,访问(如:https://i.doitim.com/oauth?client_id=53218f47acee1165829f604116c760f5&redirect_uri=http://i.doitim.com&response_type=code)

将提示用户登陆并授权。授权成功后,会自动跳转会redirect_uri的地址,并在URL地址上带成功授权的code。

比如:http://i.doitim.com/?code=f38c898541c4e9639de7c1014416382e

使用code 换取access_token 和 refresh_token

HTTP POST https://i.doitim.com/service/oauth2/token

参数:

code
client_secret
client_id
redirect_uri
grant_type=authorization_code

例如:

curl -d "code=f38c898541c4e9639de7c1014416382e&client_secret=97658ad0fec0c46afa6c2d098d4a7cb&client_id=53218f47acee1165829f604116c760f5&grant_type=authorization_code&redirect_uri=http://i.doitim.com" https://i.doitim.com/service/oauth2/token

返回信息:

    {
      "code": "200",
      "message": "success",
      "type": "oauth",
      "data": {
        "token_type": "Bearer",
        "expires_in": 7776000000,
        "access_token": "e034d9a131beab9784bc220397c418fd",
        "refresh_token": "a3b85cfed368848fa0db304378de6eb4",
        "user_id": "50e8df830cf28e61af08198e" 
        }
    }

使用refresh_token 换取access_token

HTTP POST https://i.doitim.com/service/oauth2/token

参数:

refresh_token
client_secret
client_id
redirect_uri
grant_type=refresh_token

例如

curl -d "refresh_token=a3b85cfed368848fa0db304378de6eb4&client_secret=976508ad0fec0c46afa6c2d098d4a7cb&client_id=53218f47acee1165829f604116c760f5&grant_type=refresh_token&redirect_uri=http://i.doitim.com" https://i.doitim.com/service/oauth2/token

返回信息:

{
  "code": "200",
  "message": "success",
  "type": "oauth",
  "data": {
    "token_type": "Bearer",
    "expires_in": 7776000000,
    "access_token": "20649ac6c66fc8534c20a47009e81a2a",
    "refresh_token": "a3b85cfed368848fa0db304378de6eb4",
    "user_id": "50e8df830cf28e61af08198e" 
  }
}

创建任务

HTTP POST https://i.doitim.com/service/task

access_token通过 http header 提交,如:(authorization: Bearer 20649ac6c66fc8534c20a47009e81a2a) POST数据内容 (可以是application/x-www-form-urlencoded 也可以是 JSON)

{
      title: 任务标题,字符串,不可以为空
      notes: 任务描述,字符串,可以为空
      start_at: 任务开始时间(毫秒),为1970/1/1起的毫秒数,整型,可以为空
      end_at: 任务结束时间(毫秒),为1970/1/1起的毫秒数,整型,可以为空
      all_day: 全天任务,boolean 类型,不可以为空
      tags: 标签, 为字符串数组 ["tag1"],可以为空
      project: 项目标题,字符串,可以为空
      context: 情境标题,字符串,可以为空
      goal: 目标标题,字符串,可以为空
}

服务器会根据 tags, project, context, goal 的标题找到对应的数据(如果没有该标题,则会创建新对象),然后与新创建的任务相关联。 任务默认放入收集箱,如果有开始时间,则根据开始时间放入对应的箱子。

比如:

curl -H "authorization: Bearer 20649ac6c66fc8534c20a47009e81a2a" https://i.doitim.com/service/task -d "title=test&project=new project"

得到结果

{
  "code": "200",
  "message": "success",
  "type": "task",
  "data": {
    "task_repeatno": "cae2faa0-84ca-11e3-b352-719b368c7bdc",
    "hidden": 0,
    "archived": 0,
    "completed": 0,
    "trashed": 0,
    "deleted": 0,
    "updated": 1390549227343,
    "created": 1390549227338,
    "usn": 16231,
    "title": "test",
    "uuid": "cae2faa0-84ca-11e3-b352-719b368c7bdc",
    "spent_time": 0,
    "estimated_time": 0,
    "pos": 0,
    "local_attachments": [],
    "now": false,
    "tags": [],
    "reminders": [],
    "sent_at": 0,
    "priority": 0,
    "project": "cae14cf0-84ca-11e3-b352-719b368c7bdc",
    "end_at": 0,
    "start_at": 0,
    "all_day": true,
    "attribute": "inbox" 
  }
}

错误码

http status code = 400

出错返回内容


{
  "error": "E102",
  "code": "E102",
  "message": "access_token_is_missing 未找到access_token" 
}
错误类型

code: "E100" 
  message: "invalid_request_scheme 错误的请求协议" 
code: "E101" 
  message: "invalid_request_method 错误的请求方法" 
code: "E102" 
  message: "access_token_is_missing 未找到access_token" 
code: "E103" 
  message: "invalid_access_token access_token不存在或已被用户删除,或者用户修改了密码" 
code: "E104" 
  message: "invalid_client_id client_id不存在或已删除" 
code: "E105" 
  message: "client_id_is_blocked client_id已被禁用" 
code: "E106" 
  message: "access_token_has_expired access_token已过期" 
code: "E107" 
  message: "invalid_request_uri 请求地址未注册" 
code: "E108" 
  message: "invalid_credencial1 用户未授权访问此数据" 
code: "E109" 
  message: "invalid_credencial2 client_id未申请此权限" 
code: "E110" 
  message: "not_trial_user 未注册的测试用户" 
code: "E111" 
  message: "rate_limit_exceeded1 用户访问速度限制" 
code: "E112" 
  message: "rate_limit_exceeded2 IP访问速度限制" 
code: "E113" 
  message: "required_parameter_is_missing 缺少参数" 
code: "E114" 
  message: "unsupported_grant_type 错误的grant_type" 
code: "E115" 
  message: "unsupported_response_type 错误的response_type" 
code: "E116" 
  message: "client_secret_mismatch client_secret不匹配" 
 code: "E117" 
  message: "redirect_uri_mismatch redirect_uri不匹配" 
code: "E118" 
  message: "invalid_authorization_code authorization_code不存在或已过期" 
code: "E119" 
  message: "invalid_refresh_token refresh_token不存在或已过期" 
code: "E120" 
  message: "username_password_mismatch 用户名密码不匹配" 
code: "E121" 
  message: "invalid_user 用户不存在或已删除" 
code: "E122" 
  message: "ser_has_blocked 用户已被屏蔽" 
code: "E123" 
  message: "access_token_has_expired_since_password_changed 因用户修改密码而导致access_token过期" 
code: "E124" 
  message: "access_token_has_not_expired access_token未过期" 
code: "E125" 
  message: "invalid_request_scope 访问的scope不合法,开发者不用太关注,一般不会出现该错误"