triplogs api Added by Ping Yin, last edited by Yan Jiang on Nov 19, 2012 (view change) resources field types person trail note place api 通用说明 api设计原则 通用参数说明 返回状态说明 返回值通用域说明 请求方法说明 实现注意事项 api 使用curl来测试REST api curl.post.nobody curl.post.form (application/x-www-form-urlencoded) curl.post.form (multipart/form-data) curl.put.json curl.put.file curl.delete trail api (auth) trail.post (auth) trail.put note api (auth)note.post (auth)note.upload (auth)note.put (auth)note.delete place api place.list geocoding sns api (html) sns.redirect (html) sns.callback snsapp (客户端js回调) (auth) sns.bindinfo (auth) sns.unbind (auth) sns.share (auth) sns.shareobj (auth) sns.sharetrip (auth) sns.sharenote 客户端实现第三方登陆和分享 带*的为可选域 resources field types 各个域的类型 类型 js类型 说明 int int string string url string datetime string 形如 2012-01-01 12:01:30 person { id: {string}, url: {url}, // home url nickname: {string}, } trail { id: {string}, title: {string}, cover: {url}, author: {person short}, createdAt: {datetime}, updatedAt: {datetime}, place: {place resource}, notes: [{note}], } note { id: {string}, type: {photo|text}, trail_id: {string}, pos: {int}, // start from 0. position in trail. description: {string}, place: {place resource}, lon0: {number}, // 照片的原始经度或添加note时所处的经度. null表示未知 lat0: {number}, // 同lon0,纬度 createdAt: {datetime}, updatedAt: {datetime}, *audio: { // 文本和图片都可附带一段声音 src: {url}, // amr duration: {int}, // ms mp3_src: {url}, // mp3 } // for type=photo photo: { src: {url}, width: {int}, height: {int}, } occurAt: {datetime}, // 拍摄时间 } place official place { id: {string}, // 用户创建的地点没有id name: {string}, // 北京辉煌时代家具有限公司 type: {attraction|hotel|restaurant|entertainment|shopping|other}, lon: {number}, // 经度, 如 122.32312 lat: {number}, // 纬度, 如 39.93231 } user defined place { name: {string}, // 北京辉煌时代家具有限公司 *lon: {number}, // 自定义place时, 可能没有经纬度信息 *lat: {number}, } api 通用说明 api设计原则 以可对外公布供第三方客户端使用为基本准则 参考豆瓣, google等open api的设计,尽量使用REST风格。 api的设计尽量独立于具体业务逻辑,以保证以后api的变动尽量小。 返回的resource尽量不受参数控制. 下面是一些介绍REST api设计的文章 http://www.gen-x-design.com/archives/create-a-rest-api-with-php/ http://www.lornajane.net/posts/2012/building-a-restful-php-server-understanding-the-request 拙议REST及其在PHP中的现状 通用参数说明 以下说明在每个api请求中可能包含的通用参数. 必须作为GET参数. 参数名 值 意义 备注 *callback string JSONP 回调函数名 不传则不使用JSONP. 所有返回json数据的GET api都支持jsonp, 其它api不支持 *start unsigned int 列表api起始元素的索引 从0开始. 除非特别说明, 默认为0 *limit unsigned int 列表api每页最多的结果数 除非特别说明, 默认为10 *source string 请求发起者的标识, 如 ios, android, web等 仅用作日志分析, 不会改变请求的逻辑 *fields string Response中只返回指定的域 见 google partial response *projection string 限制只返回所有域预定义的一个子集, 比如basic/full等 取值范围由所取资源支持的projection类型来定,所取默认值由各个api确定 *session_id string 认证参数. 带auth标识的api必须传此参数. 不需auth的api若非特别说明, 建议不要传此参数 登陆成功时会返回session_id 返回状态说明 1001夜 API 通过HTTP Status Code来说明 API 请求是否成功 下面的表格中展示了可能的HTTP Status Code及其含义 状态码 含义 主要场景 200 OK 请求成功 get请求成功过, 删除成功 201 Created 创建成功 rest post请求成功 202 Accepted 更新成功 rest put请求成功 400 Bad Request 请求的地址不存在或者包含不支持的参数 401 Unauthorized 未授权 带auth标志的api, 未传认证参数或参数失效或权限不够 403 Forbidden 被禁止访问 404 Not Found 请求的资源不存在 405 Method Not Allowed 服务器不支持此Request method 如只支持POST, 但发送的是GET 500 Internal Server Error 内部错误 503 Service Unavailable 服务暂时不可用 过载或维护中 当返回4xx, 5xx状态码时,可能会在Response body中返回错误消息. (由各api决定是否返回Response body) 返回值通用域说明 域 值 意义 备注 id string 资源的id items list 列表api的资源列表 start unsigned int 列表api起始元素的索引 totalResults unsigned int 列表api元素总个数 请求方法说明 方法 使用场景 GET 读取资源信息 POST 新增资源 PUT 更新资源 DELETE 删除资源 实现注意事项 带auth标志的api必须确保用户能认证通过, 如果url path中也包含了userId参数, 必须确保此userId与已授权用户的id一致,否则返回401 Unauthorized 如果不支持某Request method, 返回 405 Method Not Allowed 参数不正确应返回 400 Bad Request api 使用curl来测试REST api curl.post.nobody curl -v -X POST http://api.1001s.cn/v1/magazine/123/like curl.post.form (application/x-www-form-urlencoded) curl -v -X POST --data "username=foo&password=bar" https://api.1001s.cn/v1/auth/signup curl.post.form (multipart/form-data) 具体格式见 http://www.w3.org/TR/html401/interact/forms.html#h-17.13.4.2 curl -v -F 'name=1.jpg' -F 'file=@1.jpg' http://chanyouji2.com/upload curl.put.json curl -v -X PUT --data-binary @filename.json --header "Content-Type:application/json" http://api.1001s.cn/v1/user/me curl.put.file curl -v -X PUT --data-binary @filename.jpg --header "Content-Type:image/jpeg" http://api.1001s.cn/v1/user/me/avatar curl.delete curl -v -X DELETE http://api.1001s.cn/v1/comment/123 trail api (auth) trail.post Request POST http://api.triplogs.in1001.com/trails Content-Type: multipart/form-data Parameters (POST) 参数 值 意义 title string 游记名 *cover file 封面文件 Response 成功返回 201 Created { id: {string}, title: {string}, cover: {url}, } (auth) trail.put Request POST http://api.triplogs.in1001.com/trails/:trailId Content-Type: multipart/form-data Parameters (POST) 通用参数 _method=PUT 参数 值 意义 *title string 游记名 *cover file 封面文件 Response 同trail.post note api (auth)note.post 创建text note Request POST http://api.triplogs.in1001.com/trails/:trailId/notes Parameters (POST) 参数 值 意义 备注 pos int 位置. -1表示末尾 start from 0 description string 文本内容 *place json of place resource *lon0,*lat0 number 照片的原始经度或添加note时所处的经度 Response 成功返回 note resource 201 Created {note} (auth)note.upload Request POST http://api.triplogs.in1001.com/trails/:trailId/notes/upload Content-Type: multipart/form-data Parameters (POST) 参数 值 意义 备注 type photo/text pos int 位置. -1表示末尾 start from 0 description string 文本内容 rm_audio boolean 是否删除音频 默认 false audio_duration int 音频时长。若上传了音频文件,必须提供此字段,否则不要提供 *occurAt datetime 图片拍摄时间 *id string 若存在,更新指定note, 否则新增note *lon0, *lat0, *place 同note.post *file file 上传的图片文件 *audio_file file 上传的音频文件 Response 成功返回 note resource 200 OK {note} (auth)note.put Request PUT http://api.triplogs.in1001.com/trails/:trailId/notes/:noteId Content-Type: application/x-www-form-urlencoded; charset=UTF-8 Parameters (POST) 参数指定要更新的域和值 参数 值 意义 description string *lon0, *lat0, *place 同note.post Response 成功返回 200 OK {note} (auth)note.delete Request DELETE http://api.triplogs.in1001.com/trails/:trailId/notes/:noteId Response 成功返回 200 OK place api place.list Request GET http://api.triplogs.in1001.com/places Parameters (GET) 参数 值 意义 备注 *location string lon,lat 经纬度 搜索给定经纬度周边,为空则在整不限范围进行搜索 *q string 查询关键字 为空则列出location附近所有places location和q至少得提供一个 Response 成功返回 200 OK { totalResults: {int}, // 结果总数 start: {int}, // 返回的初始元素索引 items: [ {place resource} ] } geocoding 请使用 http://developer.baidu.com/map/geocoding-api.htm 如 http://api.map.baidu.com/geocoder?output=json&location=39.983424,116.322987&key=37492c0ee6f924cb5e934fa08c6b1676 sns api (html) sns.redirect 第三方登陆与绑定第三方账号的跳转接口,跳转到相关授权页。状态数据存到state变量。 Request GET http://passport.in1001.com/sns/redirect Parameters (GET) 参数 值 意义 备注 snsid sina/qq 平台id apptype web/android/ios 应用类型 op int 操作类型, 1: 第三方登陆, 2: 绑定 session_id string 当且仅当进行绑定操作时,传递该参数 Response 302 Redirect Location: :authorizeUrl?client_id=:app_key&response_type=code&redirect_uri=:callback_url 其中authorize url为 qq https://open.t.qq.com/cgi-bin/oauth2/authorize sina weibo https://api.weibo.com/oauth2/authorize callback url为下面的形式 {sns.callback url}?state=:state 其中state为需要传给sns.callback的编码过的信息 (包括snsid, apptype, op, *return, *session_id) 在授权页登陆成功并进行授权后后,会重定向到参数redirect_uri指定的url (sns.callback url, 带state参数) (html) sns.callback 第三方授权成功后的重定向(回调)地址。也是在开发者console中填写的地址 (sina需要精确匹配,qq前缀匹配)。在此实现相关的应用逻辑 Request GET http://triplogs.in1001.com/sns/callback Parameters (GET) 参数 值 意义 备注 state string 由sns.redirect传递过来的应用相关的数据 包含snsid, apptype, op, refer, session_id 其他参数为oauth相关的参数 Response 1. 如果为登陆操作(state.op=1) 若未绑定账号,则先利用第三方信息自动注册账号。之后的操作和已绑定账号的情况相同,如下 首先自动进行登陆操作, 然后 若为web端访问(state.apptype = "web"),设置登陆cookie,关闭认证窗口,刷新原始页面 (登陆前所处页面或state.refer指定的页面)。 若为客户端访问 (state.apptype为ios或android), 则进行js回调 snsapp.signin_ok(auth_info) 2. 如果为绑定操作 (state.op=2) 若已绑定另一账号,则web端提示绑定失败, 客户端js回调 snsapp.bind_fail(status) 若尚未绑定,则绑定到session_id对应的账号。web端关闭认证窗口,刷新原始页面。客户端js回调 snsapp.bind_ok(snsid) snsapp (客户端js回调) 客户端打开webview进行第三方登陆和绑定。完成后webview通过js回调通知客户端。方式如下 打开webview时客户端暴露snsapp对象给webview, 在此对象中实现如下方法 snsapp.signin_ok(auth_info) 登陆成功时回调 auth_info为以下object的json str { session_id: {string}, // 用作随后的api认证 expires_in: {int}, // session过期时间(秒) nickname: {string}, // 用户昵称 id: {string}, // user id } 返回的session_id可作为GET参数来进行所有带auth标识的api的认证。 snsapp.bind_ok(snsid) 绑定成功时回调, snsid为sina/qq snsapp.bind_fail(status) 绑定失败时回调,status为 ALREADY_BOUND - 已绑定到其他账户 AUTH_FAIL - 认证失败 (比如session_id失效) snsapp.close() 客户端关闭webview (auth) sns.bindinfo Request GET http://passport.in1001.com/sns/bindinfo Response 成功返回 200 OK [ { snsid: {sina|qq}, uid: {string}, // sns网站上的user id createdAt: {datetime}, updatedAt: {datetime}, expires_in: {int}, // 绑定信息过期时间(距updatedAt, 秒) } ] (auth) sns.unbind 解除绑定 Request GET http://passport.in1001.com/sns/unbind Parameters (GET) 参数 值 意义 snsid qq/sina Response 成功返回 200 OK (auth) sns.share 通用分享接口 Request POST http://passport.in1001.com/sns/share Parameters (POST) 参数 值 意义 apptype web/android/ios *type text/picture *url url 图片url content string 文本内容 snsids string separated by ',', 如 qq,sina url默认值:http://www.in1001.com/sta/images/dl_slide_1.jpg Response 返回 200 OK {boolean} // true - 成功, false - 失败 (auth) sns.shareobj 业务相关分享接口 Request POST http://api.triplogs.in1001.com/sns/shareobj Parameters (POST) 参数 值 意义 apptype web/android/ios type note/trail object type id string object id content string 文本内容 snsids string separated by ',', 如 qq,sina Response 返回 200 OK {boolean} // true - 成功, false - 失败 (auth) sns.sharetrip 分享旅程 Request POST http://api.triplogs.in1001.com/sns/sharetrip Content-Type: multipart/form-data Parameters (POST) 参数 值 意义 apptype web/android/ios id string object id content string 文本内容 snsids string separated by ',', 如 qq,sina file file 长图 Response 返回 200 OK {boolean} // true - 成功, false - 失败 (auth) sns.sharenote 分享旅程 Request POST http://api.triplogs.in1001.com/sns/sharenote Content-Type: multipart/form-data Parameters (POST) 参数 值 意义 apptype web/android/ios id string object id content string 文本内容 snsids string separated by ',', 如 qq,sina *file file 图片 Response 返回 200 OK {boolean} // true - 成功, false - 失败 客户端实现第三方登陆和分享 定义snsapp,见本文的snsapp(客户端js回调)部分 第三方登陆或绑定: 打开webview, 调用sns.redirect (传不同的参数) 需要处理用户在登陆时点击取消导致打开的窗口自行关闭的情况 分享: 调用sns.share 解除绑定: 调用sns.unbind Add Labels