Changes between Initial Version and Version 1 of web-intf-2

Timestamp:

12/30/2011 04:56:06 PM (14 years ago)

Author:

leijingtang

Comment:

--

web-intf-2

@@ +1 @@
+== 摄影部落IPAD版接口 ==
+
+=== 1.基本约定 ===
+{{{
+1.当接口处理正常时，HTTP STATUS CODE 返回给200。包括有正常的业务数据和数据为空的情况。
+
+2.当接口处理异常时，HTTP STATUS CODE 返回给500，并且给出具体的错误信息。
+    {
+        "uri" : "/intf/albums-by-type.jsp",
+        "error-code":"20502",
+        "error-desc":"Need you follow uid.",
+        "user-notice":"给用户的提示放在这里"
+    }
+
+    
+3.接口默认的字符编码是UTF-8，接口需要实现对req-enc和resp-enc参数的支持。在JSP的最顶部，实现类似下面的代码：
+
+        String queryString = request.getQueryString();
+        String requestEncoding = getParam(queryString,"req_enc");
+        String responseEncoding = getParam(queryString,"resp_enc");
+        if(isNotBlank(requestEncoding)){
+            request.setCharacterEncoding(requestEncoding);
+        }
+        if(isNotBlank(responseEncoding)){
+            response.setCharacterEncoding(responseEncoding);
+        }
+
+4.所有有写操作的数据接口，必须用POST方式提交，在接口里需要判断提交方式，拒绝GET的调用请求。
+
+5.接口中的JSON字符串，key都用双引号("")包裹，value是字符串类型时，也用双引号("")包裹；是数字类型时，不用引号。
+
+}}}
+
+
+
+== 2. 接口列表  ==
+
+=== 2.1 http://dp.pconline.com.cn/intf/ipad/albums-by-type.jsp  获取分类相册 ===
+{{{
+    HTTP请求方式：get                         
+    是否需要登录：否                          
+    请求参数：page-no：请求的页码，第一次为1。
+              page-size：每个页面的记录数。   
+              album-type：相册类型（人像：portrait,风光：landscape,生态：nature,纪实：documentary,其他：other） 
+              pick: 精华作品（0否，1是；默认为否）
+              recommend ：推荐作品（0否，1是；默认为否）
+              order-by：排序字段（by-time(按时间逆序,默认用这个排序)，by-clicks(按点击量逆序)，by-recommend-time(按推荐时间逆序，仅仅在recommend=1是有效)）
+              req-enc：请求时字符编码，缺省是UTF-8  
+              resp-enc：响应时字符编码，缺省是UTF-8 
+              time: 搜索时间范围的作品，默认time=365（即一年内的）
+
+    返回参数： 
+    { "page-no":1,
+      "page-size":10,
+      "total":100,
+      "album-type":"nature",
+      "order-by":"by-clicls",
+      "albums":[{"uid":2323,
+                "small-img-src":"http://img.pconline.com.cn/123.jpg",
+                "album-id":1233,
+                "theme":"拍摄主题",
+                "album-name":"图集名称",
+                "nickname":"摄影师昵称",
+                "is-picked":0,
+                "is-recommend":0,
+                "create-time":"yyyy-mm-dd hh:mi",
+                "vote":2233,
+                "clicks":2332
+                }]
+    }
+    page-no：请求的页码，第一次为1。
+    page-size：每个页面的记录数。
+    total：这次查询的记录总数。
+    img-src：封面图片URL
+    uid：用户id
+    album-id：图集ID
+    theme：拍摄主题
+    album-name：图集名称
+    nickname：摄影师昵称
+    is-picked：1-精华作品，0-普通作品
+    is-recommend：1-版主推荐作品，0-普通作品
+    create-time:创建时间
+    vote：所得票数
+    clicks：点击数
+
+    排序方式：图集创建时间逆序
+}}}
+
+
+=== 2.2 http://dp.pconline.com.cn/intf/ipad/search.jsp ===
+{{{
+    HTTP请求方式：get
+    是否需要登录：否
+    请求参数：kw：查询关键字
+              req-enc：请求时字符编码，缺省是UTF-8
+              resp-enc：响应时字符编码，缺省是UTF-8
+              page-no：请求的页码，第一次为1。
+              page-size：每个页面的记录数。
+              order-by：排序字段（by-time(按时间逆序,默认用这个排序)，by-clicks(按点击量逆序)）
+              time: 搜索时间范围的作品，默认time=365（即一年内的）
+    返回参数：
+    {"page-no":1,
+     "page-size":10,
+     "total":100,
+     "order-by":"by-time",
+     "kw":"蓝天白云",
+     "order-by":"by-time",
+     "result":[{"uid":23234,
+                "small-img-src":"http://img.pconline.com.cn/123.jpg",
+                "album-id":1233,
+                "theme":"拍摄主题",
+                "album-name":"图集名称",
+                "nickname":"摄影师昵称",
+                "is-picked":1,
+                "create-time":"yyyy-mm-dd hh:mi",
+                "vote":232323,
+                "clicks":2323
+                }]
+    }
+    page-no：请求的页码，第一次为1。
+    page-size：每个页面的记录数。
+    total：这次查询的记录总数。
+    order-by：结果集的排序方式。
+    kw：搜索关键字(采用UTF-8方式编码)
+    uid：用户id
+    small-img-src：封面图片URL
+    album-id：图集ID
+    theme：拍摄主题
+    album-name：图集名称
+    nickname：摄影师昵称
+    is-picked：1-精华作品，0-普调作品
+    create-time:创建时间
+    vote：所得票数
+    clicks：点击数
+
+    排序方式：图集创建时间逆序
+}}}
+
+=== 2.3 http://dp.pconline.com.cn/intf/ipad/user-photos.jsp ===
+
+{{{
+    HTTP请求方式：get
+    是否需要登录：否
+    请求参数：album-id：图集id
+              req-enc：请求时字符编码，缺省是UTF-8
+              resp-enc：响应时字符编码，缺省是UTF-8
+              page-no：请求的页码，第一次为1。
+              page-size：每个页面的记录数。
+    返回参数：    
+    {"page-no":1,
+     "page-size":10,
+     "total":100,
+     "uid":2342,
+     "logo":"http://upc.pconline.com.cn/23323.jpg",
+     "album-name":"图集名称",
+     "nickname":"摄影师昵称",
+     "is-picked":0,
+     "album-id":1233,
+     "theme":"拍摄主题",
+     "location":"拍摄地点",
+     "timer":"拍摄时间(yyyy-mm-dd)",
+     "nature":"作品性质",
+     "vote":233,
+     "clicks":23223,
+     "abstruct":"作品概括",
+     "photos":[{"photo-id":23234,
+                "small-img-src":"http://img.pconline.com.cn/123.jpg",
+                "big-img-src":"http://img.pconline.com.cn/123.jpg",
+                "exposure":"曝光方式",
+                "aperture":"光圈",
+                "shutter":"快门",
+                "iso":"iso值",
+                "ev":"曝光补偿",
+                "camera":"相机"}
+              ]
+    }
+
+    page-no：请求的页码，第一次为1。
+    page-size：每个页面的记录数。
+    total：这次查询的记录总数。
+    uid：用户id
+    logo：用户头像
+    album-name：图集名称
+    nickname：摄影师昵称
+    is-picked：1-精华作品，0-普调作品
+    album-id：图集ID
+    theme：拍摄主题
+    location：拍摄地点
+    timer：拍摄时间
+    nature：作品性质
+    vote：所得票数
+    clicks：点击数
+    abstruct：作品概括
+    photo-id：图片ID
+    small-img-src：封面图片URL
+    big-img-src：大图URL
+    exposure：曝光方式
+    aperture：光圈
+    shutter：快门
+    iso：iso值
+    ev：曝光补偿
+    camera：相机
+
+    排序方式：按图集保存的顺序，和WEB上的图片显示顺序保持一致
+}}}
+
+=== 2.4 http://dp.pconline.com.cn/intf/ipad/user-albums.jsp ===
+{{{
+    HTTP请求方式：get
+    是否需要登录：否
+    提交参数：uids：被关注的用户id集合，id之间用逗号分隔。例如(233,233232,434334,554,556534)
+              page-no：单个作者的图集分页页码
+              page-size：单个作者的图集分页数量
+              req-enc：请求时字符编码，缺省是UTF-8  
+              resp-enc：响应时字符编码，缺省是UTF-8 
+    返回参数：
+    {"users":[{"page-size":5,
+               "page-no":1,
+               "total":1,
+               "uid":1212,
+               "logo":"http://upc.pconline.com.cn/1233",
+               "user-name":"用户名称",
+               "nickname":"昵称",
+               "user-title":"用户头衔",
+               "user-address":"地区",
+               "albums":[{"album-id":3232,
+                          "small-img-src":"http://dp.pconline.com.cn/3223.jpg",
+                          "is-recommend":0},
+                         {"album-id":2343,
+                          "small-img-src":"http://dp.pconline.com.cn/3344.jpg",
+                          "is-recommend":1
+                         }]
+             }] 
+    }
+
+    page-no：单个作者的图集分页页码
+    page-size：单个作者的图集分页数量
+    total：单个作者的图集页码总数
+    uid：用户ID
+    logo：用户头像URL
+    user-name：用户名
+    nickname：用户昵称
+    user-title：用户头衔
+    user-address：用户地区
+    album-id：图集ID
+    small-img-src：图集封面URL
+    is-recommend：1-推荐作品，0-普通作品
+
+    排序方式：1、不同的用户，uids中，uid的先后顺序来进行排列。
+              2、同一个用户下的图集，先出个人推荐区的（这里按网站上个人推荐区的顺序排），后出普通图集（按图集发表时间逆序）.
+    其他：个人推荐区的数据和该用户的图集，数据是重叠的。需要进行数据去处重复的处理。
+
+}}}
+
+
+=== 2.5 http://dp.pconline.com.cn/intf/ipad/comment-post.jsp ===
+{{{
+    HTTP请求方式：post
+    是否需要登录：否，这里会有匿名评论的情况。
+    提交参数：album-id：图集id
+              req-enc：请求时字符编码，缺省是UTF-8
+              resp-enc：响应时字符编码，缺省是UTF-8
+              common_session_id：登录后的session id（非必填参数）
+              comment：评论内容
+    返回参数：
+    {"album-id":223,"comment-id":12233,"comment":"评论内容","timer":"评论时间"}
+    album-id：图集id。
+    comment-id：评论ID。
+    comment：评论正文。
+    timer：评论时间。（yyyy-mm-dd hh:mi）
+}}}
+
+=== 2.6 http://dp.pconline.com.cn/intf/ipad/comment-list.jsp ===
+{{{
+    HTTP请求方式：get
+    是否需要登录：否
+    提交参数：album-id：图集id
+              req-enc：请求时字符编码，缺省是UTF-8
+              resp-enc：响应时字符编码，缺省是UTF-8
+              page-no：请求的页码，第一次为1。
+              page-size：每个页面的记录数。
+    返回参数：
+    {"page-no":1,
+     "page-size":10,
+     "total":100,
+     "album-id":2323,
+     "comments":[{"comment-id":1233,
+                  "comment":"评论正文",
+                  "timer":"评论时间"},
+                 {"comment-id":1233,
+                  "comment":"评论正文",
+                  "timer":"评论时间"}
+                 ]
+    }
+    page-no：请求的页码，第一次为1。
+    page-size：每个页面的记录数。
+    total：这次查询的记录总数。
+    album-id：图集id
+    comment-id：评论id
+    comment：评论正文
+    timer：评论时间（格式是 yy-mm-dd hi:mm）
+    排序方式：按timer倒序
+}}}
+
+=== 2.7 http://dp.pconline.com.cn/intf/ipad/vote.jsp ===
+{{{
+    HTTP请求方式：post
+    是否需要登录：否
+    提交参数：album-id：图集id
+              device-id：设备ID
+              req-enc：请求时字符编码，缺省是UTF-8  
+              resp-enc：响应时字符编码，缺省是UTF-8 
+    其他规则：一个设备，一天内(到当天晚上的23:59:59)，只能对单个作品，投票一次
+    返回参数：
+    {"album-id":2323,"vote":2323}
+    album-id：图集ID
+    vote：投票数
+}}}
+
+
+=== 2.8 /intf/version.json ===
+{{{
+    {"version":"3.0.1","release-date":"yyyy-mm-dd","release-desc":"发布说明","release-note":"发布的新功能列表"}
+
+}}}
+
+=== 2.9 /intf/home.json ===
+{{{
+    
+}}}
+
+=== 2.10 /intf/hot-users.json === 
+{{{
+
+    HTTP请求方式：get
+    是否需要登录：否
+    提交参数：
+              page-no：单个作者的图集分页页码
+              page-size：单个作者的图集分页数量
+              req-enc：请求时字符编码，缺省是UTF-8  
+              resp-enc：响应时字符编码，缺省是UTF-8 
+    返回参数：
+    {"users":[{"page-size":5,
+               "page-no":1,
+               "total":1,
+               "uid":1212,
+               "logo":"http://upc.pconline.com.cn/1233",
+               "user-name":"用户名称",
+               "nickname":"昵称",
+               "user-title":"用户头衔",
+               "user-address":"地区",
+               "albums":[{"album-id":3232,
+                          "small-img-src":"http://dp.pconline.com.cn/3223.jpg",
+                          "is-recommend":0},
+                         {"album-id":2343,
+                          "small-img-src":"http://dp.pconline.com.cn/3344.jpg",
+                          "is-recommend":1
+                         }]
+             }] 
+    }
+
+    page-no：单个作者的图集分页页码
+    page-size：单个作者的图集分页数量
+    total：单个作者的图集页码总数
+    uid：用户ID
+    logo：用户头像URL
+    user-name：用户名
+    nickname：用户昵称
+    user-title：用户头衔
+    user-address：用户地区
+    album-id：图集ID
+    small-img-src：图集封面URL
+    is-recommend：1-推荐作品，0-普通作品
+
+    排序方式：
+              1、同一个用户下的图集，先出个人推荐区的（这里按网站上个人推荐区的顺序排），后出普通图集（按图集发表时间逆序）.
+
+    其他：个人推荐区的数据和该用户的图集，数据是重叠的。需要进行数据去处重复的处理。
+
+}}}
+
+== 3. Error Code ==
+
+    [[http://rdtrac.pc.com.cn/ipad-album/wiki/error-code|Error Code]]
+
+== 4. 修改历史 ==
+2011-12-16
+    - 修改接口2.4（{{{http://dp.pconline.com.cn/intf/ipad/user-albums.jsp}}}），使其符合框架ver1.0.4中，page-10的规则。取消is-picked输出结果，增加is-recommend参数。
+
+2011-12-15：
+    - 修改接口2.1（/intf/albums-by-type.jsp），增加time参数
+    - 修改接口2.2（/intf/search.jsp），增加time参数
+    - 接口正式地址
+    - 增加接口2.8（/intf/version.json）.这个无需实现，仅仅在发布后用来提醒网友进行版本更新。
+
+2011-12-13：
+    - 修改接口2.1（/intf/albums-by-type.jsp ），增加recommend参数和排序方式。
+    - 修正接口2.6（/intf/comment-list.jsp）去掉无用参数，补上分页参数。
+    - 完善了Error Code
+
+2011-12-12：
+    - 增加接口2.1（ /intf/albums-by-type.jsp ）、接口2.2（/intf/search.jsp）中关于排序部分的描述
+    - 增加公用错误编码