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