== 摄影部落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-new-comment（按最新评论逆序，默认用这个排序）, by-comment-count（按评论数逆序）, 
                                  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-new-comment（按最新评论逆序，默认用这个排序）, by-comment-count（按评论数逆序）, 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":"图集名称",
     "album-cover":"图集封面url",
     "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：图集名称
    album-cover：图集封面url
    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 
    返回参数：
    {   "u-page-no":1,
        "u-page-size":8,
        "u-total":2,
        "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,
                          "vote":100,
                          "clicks":100,
                          "album-name":"图集名称"},
                         {"album-id":2343,
                          "small-img-src":"http://dp.pconline.com.cn/3344.jpg",
                          "is-recommend":1,
                          "vote":100,
                          "clicks":100,
                          "album-name":"图集名称"
                         }]
             }] 
    }

    u-page-no: 用户列表页码
    u-page-size: 用户列表分页量
    u-total: 用户总数
    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-普通作品
    vote：票数
    clicks：点击数
    album-name：图集名称

    排序方式：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":"评论时间",
     "face-url":"http://www.baidu.com", 
     "nickname":"昵称", 
     "floor":"10"}


    face-url：如果存在则返回具体url，如果没有就返回空的字符串
    nickname：用户昵称
    floor：楼层数
    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":"评论时间",
                  "face-url":"http://www.baidu.com", 
                  "nickname":"昵称", 
                  "floor":"10"},
                 {"comment-id":1233,
                  "comment":"评论正文",
                  "timer":"评论时间",
                  "face-url":"", 
                  "nickname":"昵称", 
                  "floor":"10"}
                 ]
    }
    face-url：如果存在则返回具体url，如果没有就返回空的字符串
    nickname：用户昵称
    floor：楼层数
    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 http://dp.pconline.com.cn/intf/ipad/version.json ===
{{{
    {"version":"3.0.1","release-date":"yyyy-mm-dd","release-desc":"发布说明","release-note":"发布的新功能列表","url"}

}}}

=== 2.9 http://dp.pconline.com.cn/intf/ipad/home.jsp ===
{{{
    HTTP请求方式：get
    是否需要登录：否
    提交参数：types：请求的目录，目录之间用逗号隔开，该参数的顺序与返回的types的排序一致。
              req-enc：请求时字符编码，缺省是UTF-8  
              resp-enc：响应时字符编码，缺省是UTF-8 
    其他规则：该接口获取的是http://dp.pconline.com.cn摄影部落首页的4个分类中已经裁剪好的正方形图片；人像读取6张图片，另外3个分类各读取4张，一共18张。
    返回参数：
    {
    "focus-img":[
        {
            "is-ad":0,
            "small-img-src":"http://xxxx.jpg",
            "album-name":"我是标题",
            "album-id":123456
        },
        {
            "is-ad":1,
            "small-img-src":"http://xxxx.jpg",
            "album-name":"我是标题",
            "album-id":123456
        }
    ],
    "types":["portrait", "landscape", "nature", "documentary"],
    "portrait":[
        {
            "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
        }
    ],
    "landscape":[
        {
            "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
        }
    ]
}
    focus-img：焦点图数组
    is-ad：是否广告，1为是，0为否
    types：目录名称列表，表明返回的数据里包含了该列表下目录的图集列表
    portrait：目录名称，代表该目录的图集列表；与上面的types字段相关联，在types中出现的目录才会在这里。
    page-no：请求的页码，第一次为1
    page-size：每个页面的记录数
    uid：用户id
    small-img-src：封面图片URL
    album-id：图集ID
    theme：拍摄主题
    album-name：图集名称
    nickname：摄影师昵称
    is-picked：1-精华作品，0-普调作品
    create-time:创建时间
    vote：所得票数
    clicks：点击数

    排序规则：types和的排序与请求时提交的types的目录顺序一致。
}}}

=== 2.10 http://dp.pconline.com.cn/intf/ipad/hot-users.jsp === 
{{{

    HTTP请求方式：get
    是否需要登录：否
    提交参数：
              u-page-no: 用户列表页码
              u-page-size: 用户列表分页量
              page-no：单个作者的图集分页页码
              page-size：单个作者的图集分页数量
              req-enc：请求时字符编码，缺省是UTF-8  
              resp-enc：响应时字符编码，缺省是UTF-8 
    返回参数：
    {   "u-page-no":1,
        "u-page-size":8,
        "u-total":2,
        "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
                         }]
             }] 
    }

    u-page-no: 用户列表页码
    u-page-size: 用户列表分页量
    u-total: 用户总数
    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、同一个用户下的图集，先出个人推荐区的（这里按网站上个人推荐区的顺序排），后出普通图集（按图集发表时间逆序）.

    其他：个人推荐区的数据和该用户的图集，数据是重叠的。需要进行数据去处重复的处理。
          返回的用户数限定在20条，而单个用户下返回的图集数不限制。

}}}

=== 2.11 http://dp.pconline.com.cn/intf/ipad/hot-albums.jsp  获取热门作品 ===
{{{
    HTTP请求方式：get                         
    是否需要登录：否                          
    请求参数：page-no：请求的页码，第一次为1。
              page-size：每个页面的记录数
              req-enc：请求时字符编码，缺省是UTF-8  
              resp-enc：响应时字符编码，缺省是UTF-8 

    返回参数： 
    { "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：点击数

    排序方式：图集按点击数量逆序，返回结果总数限定在48条。
}}}


== 3. Error Code ==

    [[http://rdtrac.pc.com.cn/ipad-album/wiki/error-code|Error Code]]

== 4. 修改历史 ==

2012-3-7
    - 添加接口2.11  http://dp.pconline.com.cn/intf/ipad/hot-albums.jsp 

2012-2-17 
    - 修改接口2.5 http://dp.pconline.com.cn/intf/ipad/comment-post.jsp，添加字段：face-url、nickname、floor，分别为头像地址、用户昵称和楼层数，face-url如果存在就返回具体的url，否则返回一个空的字符串。
    - 修改接口2.6  http://dp.pconline.com.cn/intf/ipad/comment-list.jsp， 添加字段：face-url、nickname、floor，分别为头像地址、用户昵称和楼层数，face-url如果存在就返回具体的url，否则返回一个空的字符串。

2012-2-9
    - 修改接口2.4(user-albums.jsp) 添加点击数字段：clicks，票数字段：vote 和图集名称字段：album-name

2012-2-7
    - 修改接口2.10（hot-users.jsp）添加用户总数字段：u-total
    - 修改接口2.4（user-albums.jsp）添加用户总数字段：u-total，用户每页大小字段u-page-size，用户当前页数字段u-page-no：

2012-1-30
    - 修改接口2.3（user-photos.jsp），添加图集封面url字段：album-cover

2012-1-19
    - 修改接口2.8（version.json），添加url字段

2012-1-6
    - 添加接口2.9(/intf/home.jsp)中focus-img的album-id字段。


2011-12-30
    - 修改（/intf/hot-users.jsp）添加用户列表分页参数

2011-12-30
    - 修改接口（{{{http://dp.pconline.com.cn/intf/ipad/albums-by-type.jsp}}}），在order-by中增加了按最新评论时间和按评论数量排序的值，修改默认排序为按最新评论；请求类别（包括全部）返回的数据里，前面4个都是版主推荐的作品。精华作品例外。
    - 修改接口（{{{http://dp.pconline.com.cn/intf/ipad/search.jsp}}}），在order-by中增加了按最新评论时间和按评论数量排序的值，修改默认排序为按最新评论。
    - 增加接口（/intf/hot-users.jsp）
    - 增加接口（/intf/home.jsp）

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）中关于排序部分的描述
    - 增加公用错误编码