模仿 Github设计一个博客网站的 API

REST API的介绍
REST全称为Representational State Transfer，是表现层状态转化的意思。REST API 是前后端分离最佳实践，是开发的一套标准或者说是一套规范，不是框架。它的好处有：
1、直接通过http，不需要额外的协议，通常有post/get/put/deletec操作。
2、面向资源，一目了然，具有自解释性。
3、数据描述简单，一般通过json或者xml做数据通讯。

设计一个博客网站的API
假设访问的博客网站根地址是https://api.exampleBlog.com。

根据HTTP方法定义操作

Verb	描述
HEAD	只获取某个资源的头部信息
GET（SELECT）	从服务器取出资源
POST（CREATE）	在服务器新建一个资源
PUT（UPDATE）	在服务器更新资源（客户端提供改变后的完整资源）
PATCH（UPDATE）	在服务器更新资源（客户端提供改变的属性）
DELETE（DELETE）	从服务器删除资源

状态码
HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：

2XX	请求正常处理并返回
3XX	重定向，请求的资源位置发生变化
4XX	客户端发送的请求有错误
5XX	服务器端错误

HTTP API 设计中，经常用到的状态码以及它们的意义如下表：

状态码	Label	解释
200	OK	请求成功接收并处理，一般响应中都会有 body
201	Created	请求已完成，并导致了一个或者多个资源被创建，最常用在 POST 创建资源的时候
202	Accepted	请求已经接收并开始处理，但是处理还没有完成。一般用在异步处理的情况，响应 body 中应该告诉客户端去哪里查看任务的状态
204	No Content	请求已经处理完成，但是没有信息要返回，经常用在 PUT 更新资源的时候（客户端提供资源的所有属性，因此不需要服务端返回）。如果有重要的 metadata，可以放到头部返回
301	Moved Permanently	请求的资源已经永久性地移动到另外一个地方，后续所有的请求都应该直接访问新地址。服务端会把新地址写在 Location 头部字段，方便客户端使用。允许客户端把 POST 请求修改为 GET。
304	Not Modified	请求的资源和之前的版本一样，没有发生改变。用来缓存资源，和条件性请求（conditional request）一起出现
307	Temporary Redirect	目标资源暂时性地移动到新的地址，客户端需要去新地址进行操作，但是不能修改请求的方法。
308	Permanent Redirect	和 301 类似，除了客户端不能修改原请求的方法
400	Bad Request	客户端发送的请求有错误（请求语法错误，body 数据格式有误，body 缺少必须的字段等），导致服务端无法处理
401	Unauthorized	请求的资源需要认证，客户端没有提供认证信息或者认证信息不正确
403	Forbidden	服务器端接收到并理解客户端的请求，但是客户端的权限不足。比如，普通用户想操作只有管理员才有权限的资源。
404	Not Found	客户端要访问的资源不存在，链接失效或者客户端伪造 URL 的时候回遇到这个情况
405	Method Not Allowed	服务端接收到了请求，而且要访问的资源也存在，但是不支持对应的方法。服务端必须返回 Allow 头部，告诉客户端哪些方法是允许的
415	Unsupported Media Type	服务端不支持客户端请求的资源格式，一般是因为客户端在 Content-Type 或者 Content-Encoding 中申明了希望的返回格式，但是服务端没有实现。比如，客户端希望收到 xml返回，但是服务端支持 Json
429	Too Many Requests	客户端在规定的时间里发送了太多请求，在进行限流的时候会用到
500	Internal Server Error	服务器内部错误，导致无法完成请求的内容
503	Service Unavailable	服务器因为负载过高或者维护，暂时无法提供服务。服务器端应该返回 Retry-After 头部，告诉客户端过一段时间再来重试

上面这些状态码覆盖了 API 设计中大部分的情况，如果对某个状态码不清楚或者希望查看更完整的列表，可以参考 HTTP Status Code 这个网站，或者 RFC7231 Response Status Codes 的内容。

REST API
登录

curl -u username -p password https://api.exampleBlog.com

返回的状态码是2xx，表示成功登陆；状态码是4xx，表明请求异常，可能是以下几种错误：

报错	错误原因
400 Bad request	指令错误
401 Unauthorized	密码错误
403 Forbidden	访问过于频繁
404 Not found	账户不存在

例如：
401错误

curl -i https://api.exampleBlog.com -u foo:bar
HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials",
  "documentation_url": "https://api.exampleBlog.com"
}

403错误

HTTP/1.1 403 Forbidden
Content-Type: application/json; charset=utf-8
Connection: close
{
  "message": "You have triggered an abuse detection mechanism and have been temporarily blocked from content creation. Please retry your request again later.",
  "documentation_url": "https://api.exampleBlog/#abuse-rate-limits"
}

查看所有文章

curl -a https://api.exampleBlog.com/GoldBear98/articles

{
  "username":"GoldBear98"
  "total_count": 20,
  "articles":[
    {
      "articleID": 11,
      "title": "articleTitle",
      "owner": {
        "name": "ownerName",
        "id": 1,
        "url": "owner blog url",
        "type": "User"
      },
      "article_url": "article url"
      "private": false,
      "description": "...",
      "visits":131,
      "created_at": "2019-11-10T22:25:35Z",
      "updated_at":"2019-11-10T22:25:35Z",
      "words": 2580,
      "language": "Chinese",
      "content":"article contents...."
    },
    ...
  ]
}

关键词搜索文章

curl -k https://api.exampleBloc.com/search?keyword='cloudgo'

发布文章

curl -u -i -d '{"title":"..","content":"xxx","private":false,"description":""}' https://api.exampleBlog.com/GoldBear98/publish/article

{
 "isPublished":true ,
 "article":{
      "articleID": 1,
      "title": "articleTitle",
      "owner": {
        "name": "ownerName",
        "id": 14,
        "url": "owner blog url",
        "type": "User"
      },
      "article_url": "article url"
      "private": false,
      "description": "...",
      "reading number": 1,
      "created_at": "2019-11-19T13:23:12Z",
      "updated_at": "2018-11-19T13:23:12Z",
      "words": 2468,
      "language": "Chinese",
      "content":"article contents...."
    }
}

删除文章

curl -d -i https://api.exampleBlog.com/Goldbear98/delete/article?id=1

{
"is_deleted": "true",
"article_id": "1",
"delete_time": "2019-11-19T23:25:03Z"
}

查看评论

curl -i https://api.exampleBlog.com/Goldbear98/articles/1/comments

{
    "id": 1,
    "author": "GoldBear98",
    "url": "xxx",
    items:[
    {
     "contents":"xxx",
     "user": 
     {
       "id": 5,
       "name":"xxx",
       "url": "xxx",
       "type": "User",
     },
     ....
    ]
    "created_at": "2019-11-18T14:12:25Z",
    "updated_at": "2019-11-18T14:12:25Z"
  }

发布评论

curl  -c 'my comments' https://api.exampleBlog.com/GoldBear98/article/1/comments

{
"comment_status": "succeeded",
"comment": "my comments",
"user": "GoldBear98"
}