人间网

基本概念

renjian通过API的方式开放一些应用接口，这篇文档用来介绍renjian目前开放的接口，为希望开发基于renjian服务扩展的工具或应用的开发人员提供技术和文档服务。

• 认证

  除了部分API(如：公共时间线 ( public timeline ) )外，所有的API方法都必须要求用户认证，所有的返回都与认证用户相关。例如，尝试获取一个设置为私密的且不是您的好友的用户信息时，将会返回失败状态。

• 多状态[RESTFul]结果传输

  renjian API力求根据用户特定的请求返回对应特定格式的数据，您可以发现我们提供的API中有一个重要的便利之处，通过简单的更改URI中的文件后缀名，您可以获得您想要的返回结果的格式，这篇文档中将说明每个方法中有哪些格式可以用。
  renjian目前支持JSON,XML格式的返回结果。
  一些API接受可选和必须的参数，当参数可用时，我们会在接下来的文档中提到这些参数。注意：当传送复杂字串时，请一定先将字串编码为UTF-8格式，并再做一次URL编码 ( Encode )。

• HTTP请求

  除非特意指明，renjian的开放API通过HTTP GET方式的调用，需要提交信息或传送私密消息(如悄悄话)时使用POST方法。
  以下将说明API返回的信息格式的组成，一些API将返回与用户请求“内容”相关的信息，而有一些将返回与客户端发送的“HTTP头信息”相关的一些信息。例如，多数支持since参数的方法，同样会对HTTP头中的If-Modified-Since这个 HTTP头感兴趣。需要注意的是，当某些行为既可以通过参数又可以通过HTTP头进行控制时，优先接受通过参数方式设定的值。当请求返回数据时，返回数据的编码统一为UTF-8格式，且我们会将一些外部符号编码为HTML实体（&#number; 或&text）格式。

• HTTP状态码

  renjian API会对每次请求返回合适的HTTP状态。例如，当请求一个不存在的用户信息时，API会返回404 Not Found；当一次请求没有被认证并授权时，API会返回401 Not Authorized状态。

  1. 200 OK: 一切正常
  2. 304 Not Modified: 没有任何新数据.
  3. 400 Bad Request: 不合法的请求.
  4. 401 Not Authorized: 没有进行用户验证.
  5. 403 Forbidden: 请求被禁止访问的信息.
  6. 404 Not Found: 没有指定的记录(如用户不存在).
  7. 500 Internal Server Error: API内部错误.
  8. 502 Bad Gateway: API服务当掉或正在升级.
  9. 503 Service Unavailable: API服务负载过重，稍后再试.

  注意：

  1. 目前返回类型只支持JSON,XML格式，其他类型还没有支持
  2. 请求某个地址时，一定要加上请求返回的类型，否则无任何返回信息
     如 curl -u user:password http://api.renjian.com/statuses/friends_timeline将不会返回任何内容
     要写成curl -u user:password http://api.renjian.com/statuses/friends_timeline.json
     后续版本会加上默认类型
  3. 如果文档中的访问地址和示例有冲突或不能访问，以示例为主
  4. 所传参数尽量不要重复传，否则结果可能会不正确

用户status相关方法

• public_timeline

  返回所有用户的消息，该方法不需要身份认证。

  访问地址: http://api.renjian.com/statuses/public_timeline.format
  支持格式: json,xml
  参数列表:

  1. since_id ：若提供此参数，则仅返回消息Id值大于since_id指定值的消息。
  2. max_id ：若提供此参数，则仅返回消息Id值小于max_id指定值的消息。
  3. count ：指定获取的最大数目，不能超过500。
  4. page :可选参数，默认为第一页，分页显示使用，只能是数字。1代表第一页，2代表第二页。

  Eg:

  1. curl http://api.renjian.com/statuses/public_timeline.json
  2. curl 'http://api.renjian.com/statuses/public_timeline.json?page=2&since_id=18&max_id=55&count=5'

   

• friends_timeline

  返回最新的认证用户及其好友更新的消息，若给定下面提到的id参数时，本方法是可以用来请求其他用户的friends_timeline的。

  访问地址: http://api.renjian.com/statuses/friends_timeline.format
  支持格式: json,xml
  参数列表:

  1. since_id ：若提供此参数，则仅返回消息Id值大于since_id指定值的消息。
  2. max_id ：若提供此参数，则仅返回消息Id值小于max_id指定值的消息。
  3. count ：指定获取的最大数目，不能超过500。
  4. page :可选参数，默认为第一页，分页显示使用，只能是数字。1代表第一页，2代表第二页。

  eg:

  1. curl -u user:password http://api.renjian.com/statuses/friends_timeline.json
     当前登陆用户的friends_timeline
  2. curl -u user:password http://api.renjian.com/statuses/friends_timeline/2.json
     id为2的用户的friends_timeline
  3. curl -u user:password http://api.renjian.com/statuses/friends_timeline.json?id=2
     id为2的用户的friends_timeline
  4. curl -u user:password
     http://api.renjian.com/statuses/friends_timeline/2.json?page=2&since_id=15&max_id=50&count=5'
  5.  

• user_timeline

  返回认证用户最新更新的消息，同样，通过给定id参数，可以用来请求其他用户的最近消息更新。

  访问地址: http://api.renjian.com/statuses/user_timeline.format
  支持格式: json,xml
  参数列表:

  1. since_id ：若提供此参数，则仅返回消息Id值大于since_id指定值的消息。
  2. max_id ：若提供此参数，则仅返回消息Id值小于max_id指定值的消息。
  3. count ：指定获取的最大数目，不能超过500。
  4. page :可选参数，默认为第一页，分页显示使用，只能是数字。1代表第一页，2代表第二页。

  eg:

  1. curl -u user:password http://api.renjian.com/statuses/user_timeline.json
     当前登陆用户的user_timeline
  2. curl -u user:password http://api.renjian.com/statuses/user_timeline/2.json
     id为2的用户的user_timeline
  3. curl -u user:password http://api.renjian.com/statuses/user_timeline.json?id=2
     id为2的用户的user_timeline
  4. curl -u user:password http://api.renjian.com/statuses/user_timeline/2.json?page=2&since_id=15&max_id=50&count=5

• show

  返回指定Id的一条消息，返回中包含作者信息。

  访问地址: http://api.renjian.com/statuses/show/id.format
  支持格式: json,xml
  参数列表: id.必需，待请求消息的Id，例如：http://api.renjian.com/statuses/show/123.json
  eg:

  1. curl -u user:password http://api.renjian.com/statuses/show/2.json
     显示id为2的status
  2. curl -u user:password http://api.renjian.com/statuses/show.json?id=2
     显示id为2的status

• update

  更新认证用户的消息，必须包含status参数，且必须以POST方式请求。成功时按指定格式返回当前的消息。

  访问地址: http://api.renjian.com/statuses/update.format
  方法： POST
  支持格式: json,xml
  参数列表:

  1. text.必需，更新的消息内容， 请确定必要时需要进行UrlEncode编码，另外，不超过140.
  2. in_reply_to_status_id 可选，如果这个是回复功能使用的，如果是回复别人的消息，那么，这个字段是必须 的。是被回复的信息的id。
  3. source 可选，指明这条信息是通过什么发送的,最长12个英文字母或6个汉字，如果需要在source字段加链接，请联系 @patric。 如(web,mobile,qq)
  4. thumbnail :一般是指该status的略图.
  5. original_url : status的引用的链接地址
  6. status_type: 链接的类型，目前只有三种
     1. TEXT：普通文本，不带链接的，thumbnail和original_url都为空
     2. PICTURE：图片，original_url为原始图片地址，thumbnail为缩略图地址
     3. LINK： 带链接的status ,original_url为引用的链接，thumbnail为该链接的 缩略图地址（可选）
  7. link_title: 链接的title
  8. link_desc: 对链接的简短描述
  9. app_id: 第三方APP的ID
  10. app_name: 第三方APP的名称
  11. app_category_id: 第三方APP的分类
  12. app_ref_id: 该条status对应第三方APP信息的ID
  13. created_at: 该条status的创建日期，默认为传到服务器时的日期
  14. in_forward_status_id: 转贴的ID
  15. picture: 上传图片时，指定图片的路径，参照例子3,指定picture时，会忽略original_url和thumbnail两个参数

  eg:

  1. curl -u user:password -d 'text=xxxx'
     http://api.renjian.com/statuses/update.json
  2. curl -u user:password -d 'text=xxxx&source=xxxx'
     http://api.renjian.com/statuses/update.json
  3. 上传图片：curl -u user:password -F 'picture=@70752-Reaktor.jpg' http://api.renjian.com/statuses/update.json
  4. 通过指定图片url来上传图片：curl -u user:password -d "status_type=PICTURE&original_url=http://xxx.jpg" http://api.renjian.com/statuses/update.xml

• mentions

  显示最近的对认证用户的回复消息， ( 消息前缀为 @username ) 。该API只开放给认证用户，请求其他用户的收到的回复消息列表是非法的，无论其他用户设置私密与否。

  支持格式: json,xml
  参数列表： 跟public_timeline的参数列表使用方法一样
  eg:

  1. curl -u user:password http://api.renjian.com/statuses/mentions.json
     当前登陆用户的mentions_timeline
  2. curl -u user:password 'http://api.renjian.com/statuses/mentions.json?page=2&since_id=15&max_id=50&count=5'

• destroy

  根据指定的Id删除一条消息，认证用户必须是消息的作者或接收者。

  访问地址: http://api.renjian.com/statuses/destroy/id.format
  支持格式: json,xml
  方法：POST, DELETE
  参数列表: id.必须，待删除的消息Id
  eg:

  1. curl -u user:password -d '' http://api.renjian.com/statuses/destroy/1.json
  2. curl -u user:password -d 'id=1' http://api.renjian.com/statuses/destroy.json

用户操作接口

• Followings

  返回认证用户的朋友列表，内含每个用户的当前信息。这个方法同样可以用来请求其他用户的朋友列表，通过下面指明的方法传递id参数。

  访问地址: http://api.renjian.com/statuses/followings/ids.format
  支持格式: json,xml
  参数列表:

  id. 可选的，被请求用户的Id或者显示名称 例如：
  eg:

  1. curl -u user:password http://api.renjian.com/statuses/followings.json
     返回user的following的信息
  2. curl -u user:password http://api.renjian.com/statuses/followings/2.json
     返回id为2的用户的following的信息
  3. curl -u user:password http://api.renjian.com/statuses/followings.json?id=2
     返回id为2的用户的following的信息

• followers

  返回认证用户的订阅者，内含每个订阅者的当前信息。

  访问地址: http://api.renjian.com/statuses/followers/ids.format
  支持格式: json,xml
  eg:

  1. curl -u user:password http://api.renjian.com/statuses/followers.json
     返回user的followers的信息
  2. curl -u user:password http://api.renjian.com/statuses/followers/2.json
     返回id为2的用户的followers的信息
  3. curl -u user:password http://api.renjian.com//statuses/followers.json?id=2
     返回id为2的用户的followers的信息

• show

  显示指定用户的信息，需要给定用户的id或显示名称。

  访问地址: http://api.renjian.com/users/show/id.format
  支持格式: json,xml
  参数列表:

  id. 必须,用户的Id或显示名称
  eg:

  1. curl http://api.renjian.com/users/show.json?id=1
     显示id为1的用户的信息
  2. curl http://api.renjian.com/users/show/1.json
     显示id为1的用户的信息

悄悄话操作方法

• direct_messages

  返回发送给认证用户的消息列表

  访问地址: http://api.renjian.com/direct_messages/receive.format
  支持格式: json,xml
  参数列表:

  page， count， since_id和timeline的意思一致
  eg:
  curl -u user:password http://api.renjian.com/direct_messages/receive.json

• direct_messages_sent

  返回认证用户的发送的消息列表

  访问地址: http://api.renjian.com/direct_messages/sent.format
  支持格式: json,xml
  参数列表:

  page， count， since_id和timeline的意思一致
  eg:
  curl -u user:password http://api.renjian.com/direct_messages/sent.json

• new

  以认证用户的身份向指定的其他用户发送一条有消息，下面列出的参数user和text都是必须的，本API必须使用POST方法提交。当提交成功时，返回提交的消息。

  访问地址: http://api.renjian.com/direct_messages/new.format
  支持格式: json,xml
  方法： POST
  参数列表:

  user. 必须， 接受消息的用户Id或显示名称；
  text. 必须， 待发送消息的正文，另外，不超过140个汉字或英文。
  Eg:
  curl -u user:password -d 'user=2&text=test for doc'
  http://api.renjian.com/direct_messages/new.json

• destroy

  通过给定的消息ID，删除指定的有向消息，认证用户只能删除其作为接受者收到的消息。

  访问地址: http://api.renjian.com/direct_messages/destroy/id.format
  支持格式: json,xml
  方法: POST,DELETE
  参数列表:

  id. 必须，待删除消息的Id.
  eg:

  1. curl -u user:password -d 'http://api.renjian.com/direct_messages/destory/169.json'
     删除id为169的悄悄话
  2. curl -u user:password -d 'id=169' http://api.renjian.com/direct_messages/destory.json
     删除id为169的悄悄话

用户关系操作方法

• create

  创建认证用户与给定的ID参数指定的用户之间的好友关系；该操作执行成功时返回被加为好友的用户信息，执行失败则返回失败的状态字串。

  访问地址: http://api.renjian.com/friendships/create.format
  支持格式: json,xml
  方法：POST
  参数列表:

  id. 必须的。传入待建立好友关系的用户的Id或显示名称。如：
  eg:
  curl -u user:password -d 'id=2' http://api.renjian.com/friendships/create.json user关注id为2的用户

• destroy

  用来注销同指定id的用户的好友关系，当操作成功时，将返回被取消好友关系的用户，当失败时，将会返回失败信息。

  访问地址: http://api.renjian.com/friendships/destroy.format
  支持格式: json,xml
  方法: POST,DELETE
  参数列表:

  id. 必须的。传入待取消好友关系的用户的Id或显示名称。
  eg:
  curl -u user:password -d 'id=2' http://api.renjian.com/friendships/destory.json

• exists

  用来检验两个用户的关系是否是朋友关系或者关注与被关注的关系。如果user_a关注了user_b,返回true,否则返回false。

  访问地址: http://api.renjian.com/friendships/exists.format
  支持格式: json,xml
  方法: GET
  参数列表:

  user_a 必须
  user_b 必须
  eg:
  curl -u user:password 'http://api.renjian.com/friendships/exists.json?user_a=1&user_b=2
  user_a是否关注了user_b

• ids (followings)

  用来获取指定的用户关注(follow)的人的id

  访问地址: http://api.renjian.com/followings/ids.format
  支持格式: json,xml
  方法: GET
  参数列表:

  id. 必须，用户Id.
  Eg:

  1. curl -u user:password http://api.renjian.com/followings/ids.json
     返回user的following的ids
  2. curl -u user:password http://api.renjian.com/followings/ids/2.json
     返回id为2的用户的following的ids
  3. curl -u user:password http://api.renjian.com/followings/ids.json?id=2
     返回id为2的用户的following的id

• ids (followers)

  用来获取指定的用户被关注的用户id

  访问地址: http://api.renjian.com/followers/ids.format
  支持格式: json,xml
  方法: GET
  参数列表:

  id. 必须，用户Id. 例如： http://api.renjian.com/followers/12345.json或 http://api.renjian.com/followers/23456.json
  Eg:

  1. curl -u user:password http://api.renjian.com/followers/ids.json
     返回user的followers的ids
  2. curl -u user:password http://api.renjian.com/followers/ids/2.json
     返回id为2的用户的followers的ids
  3. curl -u user:password http://api.renjian.com/followers/ids.json?id=2
     返回id为2的用户的followers的ids

收藏

• favorites

  返回用户的最新的收藏的信息。也可以通过id或者用户名来指定一个用户，查询他最新的收藏的信息。

  访问地址: http://api.renjian.com/favorites/list.format
  支持格式: json,xml
  参数列表:
  目前只支持page参数

  eg:

  1. curl -u username:password http://api.renjian.com/favorites/list.json
  2. 当前登陆者的收藏列表
     curl -u username:password http://api.renjian.com/favorites/list.json?page=2

• create

  收藏一条信息

  访问地址: http://api.renjian.com/favorites/create/id.format
  支持格式: json,xml
  方法： POST
  参数列表:

  id 必须，用户要收藏的信息id。
  Eg:

  1. curl -u user:password -d 'id=101' http://api.renjian.com/favorites/create.json
     收藏id为1的status
  2. curl -u user:password -d '' http://api.renjian.com/favorites/create/1.json
     收藏id为1的status

• destroy

  删除用户收藏的一条信息

  访问地址: http://api.renjian.com/favorites/destroy/id.format
  支持格式: json,xml
  方法： POST,DELETE
  参数列表:

  id用户要删除收藏的信息id。
  Eg:

  1. curl -u user:password -d 'id=101' http://api.renjian.com/favorites/destroy.json
     取消收藏id为1的status
  2. curl -u user:password -d '' http://api.renjian.com/favorites/destroy/1.json
     取消收藏id为1的status

用户个人资料，和设置方面

• update_profile

  修改用户的账户基本信息，必须采用post方法提交。

  访问地址：http://api.renjian.com/account/update_profile.format
  支持格式：json,xml
  参数列表：

  nickname 用户的昵称
  username 用户名
  location 用户的所在地
  email 用户的联系email
  url
  description
  eg:
  curl -u user:gemini -d 'nickname=xx&username=xx&email=xx&url=xx&location=xx&description=xxx' http://api.renjian.com/account/update_profile.json

• block

  block某个用户，必须采用post方法提交。

  访问地址：http://api.renjian.com/blocks/create.json
  支持格式：json,xml
  参数列表：

  id
  eg:

  1. curl -u user:password -d 'id=3' http://api.renjian.com/blocks/create.json
  2. curl -u user:password -d '' http://api.renjian.com/blocks/create/3.json

• unblock

  取消block某个用户

  访问地址：http://api.renjian.com/blocks/destory.json
  支持格式：json,xml
  参数列表： id

  Eg:

  1. curl -u user:password -d 'id=3' http://api.renjian.com/blocks/destory.json
  2. curl -u user:password -d '' http://api.renjian.com/blocks/destory/3.json

用户验证

• verify

  为了避免API每次都传用户名和密码，可以通过verify方法执行类似登陆的一个操作，服务器会在cookie中加一个名为_renjian_sess_c的cookie，用户以后可以每次把这个值放在request的cookies中，这样就可避免每次都传用户名和密码过来

  访问地址：http://api.renjian.com/account/verify_credentials
  支持格式：json,xml
  方法： POST,HEAD

  eg:

  1. curl -u username:password -I http://api.renjian.com/account/verify_credentials.json
     返回中会有Set-Cookie: _renjian_sess_c=64sdasdlu9123123;Path=/
  2. 再次请求时
     curl -b '_renjian_sess_c=64sdasdlu9123123' http://rennsea.com/statuses/mentions.json

会话

这部分API还在测试中，以后可能会做更改，如排序等，目前以下三个API都需要验证，以后会根据需要去掉。大家如果有任何想法或建议，可以@niedhui 或发邮件给dianhui.nie@gmail.com.：)

• 我发起的会话

  返回当前登陆用户发起与的会话

  访问地址: http://api.renjian.com/conversations/my_conversations.format
  支持格式: json,xml
  参数列表:

  1. since_id ：若提供此参数，则仅返回消息Id值大于since_id指定值的消息。
  2. count ：指定获取的最大数目，不能超过500。
  3. page :可选参数，默认为第一页，分页显示使用，只能是数字。1代表第一页，2代表第二页。

  Eg:

  1. curl -u username:password http://api.renjian.com/conversations/my_conversations.json
  2. curl -u username:password 'http://api.renjian.com/conversations/my_conversations.json?page=2&count=5'

   

• 某条status对应的会话

  由于某种原因，这个API返回的status排序和其它timeline的顺序不一样，其他API的第一页返回的是最新的，这个API的第一页返回的是最旧的， 这部分以后有可能会和其它timeline保持一致

  根据传入的status的ID返回status对应的会话里的所有status,如果传入的ID不构成会话，则会返回404

  访问地址: http://api.renjian.com/conversations/show_by_status/id.format
  支持格式: json,xml
  参数列表:

  1. id ： status 的ID
  2. count ：指定获取的最大数目，不能超过500。
  3. page :可选参数，默认为第一页，分页显示使用，只能是数字。1代表第一页，2代表第二页。
  4. show_all :可选参数，如果这个参数为true,则返回会话里所有的status,忽略page和count参数。

  Eg:

  1. curl -u username:password http://api.renjian.com/conversations/show_by_status/254086.json
  2. curl -u username:password 'http://api.renjian.com/conversations/show_by_status.json?id=2&page=2&count=5'

   

• 某个会话对应的所有status

  由于某种原因，这个API返回的status排序和其它timeline的顺序不一样，其他API的第一页返回的是最新的，这个API的第一页返回的是最旧的， 这部分以后有可能会和其它timeline保持一致

  如果你知道某会话ID,可以直接据会话ID来获取所有会话对应的status

  访问地址: http://api.renjian.com/conversations/statuses.format
  支持格式: json,xml
  参数列表:

  1. count ：指定获取的最大数目，不能超过500。
  2. page :可选参数，默认为第一页，分页显示使用，只能是数字。1代表第一页，2代表第二页。
  3. show_all :可选参数，如果这个参数为true,则返回会话里所有的status,忽略page和count参数。
  4. since_id :若提供此参数，则仅返回消息Id值大于since_id指定值的消息。

  Eg:

  1. curl -u username:password http://api.renjian.com/conversations/statuses/250146.json
  2. curl -u username:password 'http://api.renjian.com/conversations/statuses.json?id=250146&page=2&count=5'

   

圈子API

• tag timeline

  返回某个圈子的timeline

  访问地址：http://api.renjian.com/tag/tag_timeline/tagName.format
  支持格式：json,xml
  方法： GET,HEAD

  eg:

  1. curl http://api.renjian.com/tag/tag_timeline/ipad.json
     
  2. curl http://api.renjian.com/tag/tag_timeline/ipad.xml

• tag essence timeline

  返回某个圈子精华的timeline

  访问地址：http://api.renjian.com/tag/tag_essence_timeline/tagName.format
  支持格式：json,xml
  方法： GET,HEAD

  eg:

  1. curl http://api.renjian.com/tag/tag_essence_timeline/ipad.json
     
  2. curl http://api.renjian.com/tag/tag_essence_timeline/ipad.xml

返回数据内容

• direct_message

  id: message的id
  sender_id: 发送人的ID
  text: 发送的内容
  recipient_id: 接收人的ID
  created_at: 发送时间(unix time)
  sender_screen_name: 发送人的screen name
  recipient_screen_name:接收人的screen name
  sender: 发送人的详细信息
  recipient: 接收人的详细信息

• 用户信息

  id: 用户ID
  name：用户的昵称
  screen_name:用户名
  gender: 用户的性别(0表示未知，1表示男，2表示女)
  description: 用户的描述
  profile_image_url: 用户的头像
  protected: 用户是否设定保护更新
  created_at: 用户的注册日期(unix time)
  followers_count: followers的数量
  following_count: followeing的数量
  favourites_count: 收藏的数量
  如果当前用户为认证用户，将多返回两个字段：
  is_followed_me:请求的用户是否关注当前用户：0为不关注
  is_following: 当前用户是否关注请求的用户：0 为不关注

• status

  id: status的Id
  created_at: status的创建日期
  text: status的文本内容
  source: status的来源
  truncated: status的text是否因为过长而截断
  in_reply_to_status_id: 回应的status的id
  in_reply_to_user_id: 回应的status的发送者的id
  in_reply_to_screen_name:回应的status的作者的screenName
  favorited: 当前用户是否收藏了这条status
  original_url: 引用的链接
  status_type: status的类型
  link_title: 引用的链接的title
  link_desc: 引用的链接的描述
  thumbnail: 缩略图
  app_id:
  app_name:
  app_category_id:
  app_ref_id:
  root_screen_name:
  root_status_id:发生转贴时，整个链中的第一条status的id

• 会话

  id: 会话的Id
  last_status_id: 会话最后一条status的id
  text: 会话的文本内容（第一条status的text）
  unread_count: 该会话未读status数
  owner: 会话的发起者（拥有者）