博客网站的API设计

设计博客网站的的部分REST API

本篇博客的主要目的是模仿github API，编写设计一个博客网站的部分REST API。
在字博客中使用的博客网站域名为

https://api.MyExampleBlog.com

1.REST

REST是Representational State Transfer（表现层状态转移）的缩写，它是由罗伊·菲尔丁（Roy Fielding）提出的，是用来描述创建HTTP API的标准方法的，这就是说REST作为一个对HTML设计的一种风格，通过这种风格化的设计能够跟有效的设计出HTTP API 的实现方式与内容。

2.设计原则

HTTP 协议定义了大量为请求赋于语义的方法。 大多数 RESTful Web API 使用的常见 HTTP 方法是：

• GET 检索位于指定 URI 处的资源的表示形式。 响应消息的正文包含所请求资源的详细信息。
• POST 在指定的 URI 处创建新资源。 请求消息的正文将提供新资源的详细信息。 请注意，POST 还用于触发不实际创建资源的操作。
• PUT 在指定的 URI 处创建或替换资源。 请求消息的正文指定要创建或更新的资源。
• PATCH 对资源执行部分更新。 请求正文包含要应用到资源的一组更改。
• DELETE 删除位于指定 URI 处的资源。
  而主要的API的实现也要围绕着这样的HTTP动词来进行设计。
  主要的返回状态码

名称	返回结果
200	OK (默认的)
201	Created（已创建）
202	Accepted (已接受：常用语删除请求)
400	请求出错（语法格式有误或服务器无法理解此请求）
401	未授权(需要登录)
404	找不到 (找不到所请求的文件或脚本)
405	不允许此方法(错误的 HTTP方法)
409	冲突 (IE尝试以PUT请求创建相同的资源时)
5xx	Server error（服务器端错误）

Schema
发送与接受的数据都以JSON方式传输，例如：当获取一个博客的信心是返回的信息为：

curl -i https://api.MyExampleBlog.com/users
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 22 Nov 2019 14:41:53 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-MyExampleBlog-Media-Type: github.v3
X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4987
X-RateLimit-Reset: 1350085394
Content-Length: 5
Cache-Control: max-age=0, private, must-revalidate
X-Content-Type-Options: nosniff

3.API设计

登录博客账号

curl -u username:password https://api.MyExampleBlog.com/

获取博客信息

curl -i https://api.MyExampleBlog.com/users

可能的返回结果是：

{
  "username":"user"
  "articles":[
    {
      "title":"XXXX",
      "href":"https://api.MyExampleBlog.com/user/article/1001",
      "action":"GET",
      "status":"original"
      "words": 1629,
      "visits": 508
    },
   ]
}

发布一个新的博客

POST https://api.MyExampleBlog.com/user/article/1002

发布文章的API需要提供文章的标题等相关信息

curl -u -i -d '{"title":"..","content":"xxx","private":false,"description":""}' https://api.MyExampleBlog.com/user/article/1002

信息内容为：

{
"content":"文章内容",
"title":"文章标题",
"private":true/false,//是否公开
"description":"说明"
}

返回信息为：

{
	"isPublished":true ,
	"article":{
      "articleID": 10,
      "name": "articleNames",
      },
      "article_url": "article url"
      "private": false,
      "description": "...",
      "reading number": 0,
      "words": 4828,
      "content":"article contents...."
    },
}

删除文章
删除文章需要提供文章id

curl -i -u https://api.MyExampleBlog.com/user/delete/article&id=1002

返回信息为

{
	"isDeleted":true / false,
	"id" : 10
}