API 使用手册

相对于浏览器访问网页的形式，通过[API][1]来访问网络资源相对而言难度较大，但是通过API的方式能直接得到想要的数据，省去了浏览器加载各种静态资源的麻烦，因此效率和速度也要快不少。 # API的使用方法 ## 1. 获取API key 通过token的方式来验证，因此token很重要，获取token的方式是先访问[用户界面][2]，选择*API key*选择项，点击*Generate new API key*按钮即可看到生成的API key，是40位长的字符串。 ## 2. 字段的填写 发送请求的方式有很多种，可以通过类似*Postman*的插件来发送，也可以通过curl来发送。 首先是请求头的填写，主要需要包含两个header，分别是content类型和authorization，其中部分api不需要authorization，后文详述。 一个是`Content-Type: application/json`，另一个是`Authorization: Token `**`API_key`**，其中**`API_key`**就是前面获取的40位长的API key，示例: `Authorization: Token 698e6123fa8444751f2344d5b89e7639f03866ed`，注意后文所有示例的API_key都是**无效**的，需要填写**你自己**的API_key! 然后是发送的方法，不同的api要求不同的方法，下文详述。 接着是发送的数据，不同api要求不同的数据，下文详述。 最后是请求的api地址，如果采用GET方法还需要在url后加上参数，整个url需要用引号括起来，下文详述。 ***特别注意，Windows系统下url地址需要用双引号括起来，而Linux系统单双引号都可以！*** ## 3. 请求的发送 将请求的头部填好，使用合适的方法讲数据发送到对应url就是整个发送的过程。对于不同的api，有些需要发送数据，有些则不需要，有些需要用POST方法发送，有些则需要GET方法。 以curl为例，使用`-X`指定发送方法，使用`-H`发送头部，使用`-d`发送数据。一个典型的api call如下。 ``` curl -X POST 'http://127.0.0.1:8000/api/blogs/post/' -H "Content-Type: application/json" -H 'Authorization: Token 78c94f35184bbdd0e36ed1dbc0dae490ebb86316' -d '{"title": "This is a blog created by calling api", "text": "This is done via `curl`, authenticated via `token`", "categories": "test api"}' ``` 这个命令的解读如下。首先看`-X`，后面参数是POST，即使用POST方法来发送数据，然后是api地址，即`http://127.0.0.1:8000/api/blogs/post/`，然后是`-H` 后面接的就是头部**Content-Type**，然后又是`-H`，这次是api key验证字段，最后是`-d`字段，后面接了一个字典，也就是发送的数据字段。 # API参考手册 ## 1. 查看博客API ### 功能: 查看已经发布的博客 ### 地址: https://chongliu.me/api/blogs/ ### 发送方式: [GET] ### 发送数据: 无 ### 参数: [page, page_size] page表示当前的页码，page_size表示一页显示多少项目。这两个参数都是可选的。 ### 权限: 所有用户 ### 实例: ``` curl -X GET 'https://chongliu.me/api/blogs/?page=2&page_size=8' -H "Content-Type: application/json" ``` ### 返回字段: 1. count: 总共的博客条数 2. previous: 前一页的url 3. next: 后一页的url 4. results: 返回的结果 ## 2. 查看博客详细信息API ### 功能: 查看某一博客的具体信息 ### 地址: https://chongliu.me/api/blogs/archive/ *blog_id* / *blog_id*: 博客的id ### 发送方式: [GET] ### 发送数据: 无 ### 参数: 无 ### 权限: 所有用户 ### 实例: ``` curl -X GET 'https://chongliu.me/api/blogs/archive/105/' -H "Content-Type: application/json" ``` ### 返回字段: 1. id: 博客id 2. title: 博客的标题 3. author: 作者的名字 4. publish_time: 发布的时间 5. last_update_time: 最后修改时间 6. text: 博客正文 7. categories: 博客标签 ## 3. 更新博客API ### 功能: 更新某一博客的具体信息 ### 地址: https://chongliu.me/api/blogs/archive/ *blog_id* /edit/ *blog_id*: 博客的id ### 发送方式: [PUT] ### 发送数据: ``` { "title": "", "text": "", "categories": "" } ``` 其中三个数据段都是可选的。有哪个数据段就更新哪个数据段。其中categories字段将所有的category用空格隔开，如果categories字段留的字段是空字符串的话会移除所有标签。 ### 参数: 无 ### 权限: 仅限该博客的作者 ### 实例: ``` curl -X PUT 'https://chongliu.me/api/blogs/archive/19/edit/' -H 'Authorization: Token 78c94f35184bbdd0e36ed1dbc0dae490ebb86316' -H "Content-Type: application/json" -d '{"title": "测试2 modified", "text": "test now!", "categories": "test 测试"}' ``` ### 返回字段: 1. title: 修改后的标题 2. text: 修改后的正文 3. categories: 修改后的标签 ## 4. 新建博客API ### 功能: 发表一条博客 ### 地址: https://chongliu.me/api/blogs/post/ ### 发送方式: [POST] ### 发送数据: ``` { "title": "", "text": "", "categories": "" } ``` 其中"title", "text"为必填字段，"categories"为选填字段。 ### 参数: 无 ### 权限: 所有登录用户 ### 实例: ``` curl -X POST 'https://chongliu.me/api/blogs/post/' -H 'Authorization: Token 78c94f35184bbdd0e36ed1dbc0dae490ebb86316' -H "Content-Type: application/json" -d '{"title": "测试 API 发送", "text": "测试成功!", "categories": "test 测试"}' ``` ### 返回字段: 1. id: 新建博客的id 2. title: 新建博客的标题 3. text: 新建博客的正文 4. categories: 新建博客的标签 ## 5. 查看博客评论API ### 功能: 查看某一博客的所有评论 ### 地址: https://chongliu.me/api/blogs/archive/ *blog_id* /comment/ *blog_id*: 博客的id ### 发送方式: [GET] ### 发送数据: 无 ### 参数: 无 ### 权限: 所有用户 ### 实例: ``` curl -X GET 'https://chongliu.me/api/blogs/archive/2/comment/' -H "Content-Type: application/json" ``` ### 返回字段: 1. comments: 所有的评论，以json格式存储，为树形结构，每一个节点包含以下字段: id: 评论id, author: 评论作者, publish_time: 发布时间, last_update_time: 最后更新时间, text: 正文, children: 子节点。 ## 6. 查看评论API ### 功能: 查看某一评论及子评论 ### 地址: https://chongliu.me/api/blogs/comment/ *comment_id* / *comment_id*: 评论的id ### 发送方式: [GET] ### 发送数据: 无 ### 参数: 无 ### 权限: 所有用户 ### 实例: ``` curl -X GET 'https://chongliu.me/api/blogs/comment/260/' -H "Content-Type: application/json" ``` ### 返回字段: 1. id: 评论id 2. author: 作者的名字 3. publish_time: 发布的时间 4. last_update_time: 最后修改时间 5. text: 评论正文 6. children: 子节点。 ## 7. 回复博客API ### 功能: 对一条博客进行回复 ### 地址: https://chongliu.me/api/blogs/addComment/ *blog_id* / *blog_id*: 博客的id ### 发送方式: [POST] ### 发送数据: ``` { "text": "" } ``` "text"为必填字段，为回复正文。 ### 参数: 无 ### 权限: 所有登录用户 ### 实例: ``` curl -X POST 'https://chongliu.me/api/blogs/addComment/19/' -H 'Authorization: Token 78c94f35184bbdd0e36ed1dbc0dae490ebb86316' -H "Content-Type: application/json" -d '{"text": "测试回复博客"}' ``` ### 返回字段: 1. id: 新回复的id 2. text: 新回复的正文 ## 8. 回复评论API ### 功能: 对一条评论进行回复 ### 地址: https://chongliu.me/api/blogs/addNestedComment/ *comment_id* / *comment_id*: 评论的id ### 发送方式: [POST] ### 发送数据: ``` { "text": "" } ``` "text"为必填字段，为回复正文。 ### 参数: 无 ### 权限: 所有登录用户 ### 实例: ``` curl -X POST 'https://chongliu.me/api/blogs/addNestedComment/268/' -H 'Authorization: Token 78c94f35184bbdd0e36ed1dbc0dae490ebb86316' -H "Content-Type: application/json" -d '{"text": "测试回复评论"}' ``` ### 返回字段: 1. id: 新回复的id 2. text: 新回复的正文 ## 9. 更新评论API ### 功能: 更新某一评论的内容 ### 地址: https://chongliu.me/api/blogs/comment/ *comment_id* /edit/ *comment_id*: 评论的id ### 发送方式: [PUT] ### 发送数据: ``` { "text": "" } ``` "text"为必填字段，为回复正文。 ### 参数: 无 ### 权限: 仅限该评论的作者 ### 实例: ``` curl -X PUT 'https://chongliu.me/api/blogs/comment/268/edit/' -H 'Authorization: Token 78c94f35184bbdd0e36ed1dbc0dae490ebb86316' -H "Content-Type: application/json" -d '{"text": "updated comment"}' ``` ### 返回字段: 1. text: 更新后的回复正文 ## 10. 查看标签下的博客API ### 功能: 查看所有含某标签的博客 ### 地址: https://chongliu.me/api/blogs/category/ *name* / *name*: 标签名称 ### 发送方式: [GET] ### 发送数据: 无 ### 参数: [page, page_size] page表示当前的页码，page_size表示一页显示多少项目。这两个参数都是可选的。 ### 权限: 所有用户 ### 实例: ``` curl -X GET 'https://chongliu.me/api/blogs/category/test/?page=2&page_size=3' -H "Content-Type: application/json" ``` ### 返回字段: 1. count: 该标签下总共的博客条数 2. previous: 前一页的url 3. next: 后一页的url 4. results: 返回的结果 ## 11. 搜索博客API ### 功能: 查看所有在某字段含有指定搜索内容的博客 ### 地址: https://chongliu.me/api/blogs/search/ ### 发送方式: [GET] ### 发送数据: 无 ### 参数: search, [page, page_size, title, text, author, category, publish_from_date, publish_to_date, update_from_date, update_to_date] 其中search字段为搜索内容，是必选字段，其他都是可选字段 page表示当前的页码，page_size表示一页显示多少项目。 当参数含有title时(不必赋值)，则会搜索所有标题含搜索字段的博客，同理text(正文字段)，author(作者名字)，category(标签名字)。需注意的是这4个人标签有同时出现的情况时，将会把所有的搜索结果合并，相当于取**或运算**，不是与运算。 当参数含有publish_from_date时，需要赋值，表示从某个日期开始发布的博客，格式**年-月-日**，如"2017-1-2"，"2017-03-09"等等。同理publish_to_date(发布时间在某日期之前), update_from_date(最后更新时间在某日期之后), update_to_date(最后更新日期在某日期之前)。需注意的是这四个标签同时出现的情况，会把所有条件合并选取，相当于**与运算**，不是或运算。同时还需注意如果要选择*2017年2月14日0时0分0秒*到*2017年2月14日23时59分59秒*所有发布的博客，参数应该是`?publish_from_date=2017-2-14&publish_to_date=2017-2-15`，*publish_to_date*应该是*2017-2-15*而不是*2017-2-14*。 ### 权限: 所有用户 ### 实例: ``` curl -X GET 'https://chongliu.me/api/blogs/search/?search=test&page=2&page_size=3&title&category&publish_from_date=2017-2-14&publish_to_date=2017-3-1' -H "Content-Type: application/json" ``` ### 返回字段: 1. count: 该搜索条件下总共的博客条数 2. previous: 前一页的url 3. next: 后一页的url 4. results: 返回的结果 [1]: https://en.wikipedia.org/wiki/Web_API [2]: https://chongliu.me/accounts/profile/