== 摄影部落IPAD版接口 ==

=== 基本约定 ===
{{{
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是字符串类型时，也用双引号("")包裹；是数字类型时，不用引号。

}}}





=== 1. /intf/albums-by-type.jsp  获取分类相册 ===
{{{
    HTTP请求方式：get                         
    是否需要登录：否                          
    请求参数：page-no：请求的页码，第一次为1。
              page-size：每个页面的记录数。   
              album-type：相册类型（最新精华：pick,人像：portrait,风光：landscape,生态：nature,纪实：documentary,其他：other） 
              order: 排序方式（0为按时间排，最新在前；1为按点击数拍，最多在前；默认是按时间排）
              req-enc：请求时字符编码，缺省是UTF-8  
              resp-enc：响应时字符编码，缺省是UTF-8 


    返回参数： 
    {"albums":[{"uid":2323,
                "small-img-src":"http://img.pconline.com.cn/123.jpg",
                "album-id":1233,
                "theme":"拍摄主题",
                "album-name":"图集名称",
                "nickname":"摄影师昵称",
                "vote":2233,
                "clicks":2332
                }]
    }
    page-no：请求的页码，第一次为1。
    page-size：每个页面的记录数。
    img-src：封面图片URL
    uid：用户id
    album-id：图集ID
    theme：拍摄主题
    album-name：图集名称
    nickname：摄影师昵称
    vote：所得票数
    clicks：点击数

    排序方式：图集创建时间逆序
}}}


=== 2. /intf/search.jsp ===
{{{
    HTTP请求方式：get
    是否需要登录：否
    请求参数：kw：查询关键字
              order: 排序方式（0为按时间排，最新在前；1为按点击数拍，最多在前；默认是按时间排）
              req-enc：请求时字符编码，缺省是UTF-8
              resp-enc：响应时字符编码，缺省是UTF-8
              page-no：请求的页码，第一次为1。
              page-size：每个页面的记录数。
              order-by：排序字段（by-time(按时间逆序)，by-clicks(按点击量逆序)）
    返回参数：
    {"page-no":1,
     "page-size":10,
     "total":100,
     "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":"摄影师昵称",
                "vote":232323,
                "clicks":2323
                }]
    }
    page-no：
    page-size：
    kw：搜索关键字(采用UTF-8方式编码)
    uid：用户id
    small-img-src：封面图片URL
    album-id：图集ID
    theme：拍摄主题
    album-name：图集名称
    nickname：摄影师昵称
    vote：所得票数
    clicks：点击数

    排序方式：1、图集创建时间逆序
              2、按照点击数量逆序
}}}

=== 3. /intf/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":"摄影师昵称",
     "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：用户头像
    nickname：用户昵称
    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上的图片显示顺序保持一致
}}}

=== 4./intf/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",
                          "picked":0},
                         {"album-id":2343,
                          "small-img-src":"http://dp.pconline.com.cn/3344.jpg",
                          "picked":1
                         }]
             }] 
    }

    page-no：单个作者的图集分页页码
    page-size：单个作者的图集分页数量
    total：单个作者的图集页码总数
    uid：用户ID
    logo：用户头像URL
    user-name：用户名
    nickname：用户昵称
    user-title：用户头衔
    user-address：用户地区
    album-id：图集ID
    small-img-src：图集封面URL
    picked：精华作品（0：非精华，1：精华）

    排序方式：1、不同的用户，uids中，uid的先后顺序来进行排列。
              2、同一个用户下的图集，先出精华的（按图集发表时间逆序），后出普通图集（按图集发表时间逆序）.

}}}


=== 5. /intf/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）
}}}

=== 6. /intf/comment-list.jsp ===
{{{
    HTTP请求方式：get
    是否需要登录：否
    提交参数：album-id：图集id
              req-enc：请求时字符编码，缺省是UTF-8
              resp-enc：响应时字符编码，缺省是UTF-8
              comment：评论内容
    返回参数：
    {"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倒序
}}}

=== 7. /intf/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：投票数
}}}


=== 修改历史 ===

2011-12-12：
    -增加接口2（/intf/search.jsp）中关于排序部分的描述