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