基于markdown的博客网站Rest API设计

本次作业基于markdown编写了一个模仿github api的rest api

数据架构

由于Http是唯一与REST相关的实例，本文的实现通过HTTP实现REST，所有的API访问基于HTTPS进行

访问博客网站的API，https://api.BlogExample.com来进行数据的访问，所有数据通过JSON形式进行发送和接收

资源是 Restful API 的核心元素，所有的操作都是针对特定资源进行的。而资源就是 URL（Uniform Resoure Locator）表示的

基于HTTP，有五个常用的动词，动词常用的HTTP请求方式如下

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。

实际上的请求发送通过curl实现

Rest Api设计

用户登陆

用户登陆授权可以通过两种方式进行访问

通过curl加上用户名的方式进行登入，登入时需要输入密码

curl -u "username" https://api.blogexample.com

此时会弹出相应的密码弹出框，输入对应的密码后可以成功登入博客网站

还可以通过参数中加入密码，直接进行访问

curl -i https://api.blogexample.com -u "username"："password"

访问后收到的响应信息包含响应状态码，相关信息和url

访问出错信息示例如下

HTTP/1.1 401 Unauthorized
{
  "message": "Bad credentials",
  "documentation_url": "https://developer.blogexample.com"
}

访问成功后会返回2XX状态码，表示输入的密码正确，成功登入网站，返回字段包括成功登入信息和账号信息，和错误一样，响应信息也作为一个资源单独处理

HTTP/1.1 200 OK
{
  "message": "GET success",
  "userName": "user1"
}

查看第n页的博客

查看博客通过GET请求访问指定页面的博客，且需要指定每一页显示的文章数量

请求如下：GET /:username/myblog

需要的data参数包含page的序号和per_page表示每一页显示的文章数量

下述指令表示访问user1用户中第二页的所有文章，每一页显示的文章数量为10

curl -i 'https://api.blogexample.com/user1/myblog?page=2&per_page=10'

请求成功的话会产生一个资源，包含博客的超链接和用户的基本信息

HTTP/1.1 200 OK

{ 
	"userid"=123456789, 
	"blognum"=123, 
	"userName"= "user1", 
	"links": {
		"myblog1": "/myblog/01",
		"myblog2": "/myblog/02",
...
            "myblog10": "/myblog/10",
	}
}

博客文章信息读取

博客读取可以通过GET请求实现，读取博客的相关信息

请求如下：GET /:username/myblog

需要的参数为文章的id blog_id，通过id进行文章的定位

curl -i 'https://api.blogexample.com/user1/myblog?blog_id=01'

请求成功即文章存在时返回文章的内容，文章内容同样作为资源返回，访问出错会返回错误信息，读取成功的字段示例如下

HTTP/1.1 200 OK

{ 
	“userName”: "user1",
    "blogId": 01,
    "content":{
        ......
    }
}

删除博客

博客的删除可以通过DELETE执行，提供博客的指定id，并删除对应的博客

请求如下: DELETE /:username/myblog/delete

提供的参数为文章ID

curl -i 'https://api.blogexample.com/user1/myblog/delete?blogid=05'

请求发送成功返回200 OK表示资源已被删除，如果资源不存在返回的状态码为404，返回资源字段示例如下

HTTP/1.1 404 Not Found
{
  "message": "blog doesn't exist",
  "documentation_url": "https://developer.blogexample.com"
}

 

发布博客

发布博客采用POST指令在服务器新建一个资源，需要提供的参数为文章的内容和标题

请求如下： POST /:username/myblog/publish

需要以JSON形式向服务器发送需要新建的博客标题和内容，命令示意如下

curl -i 'https://api.blogexample.com/user1/myblog/publish' -d '{"title":"mytitle","content":"content...."}' 

博客新建成功后会返回201表示资源成功创建，返回的资源包括系统为博客分配的ID和博客的链接等字段，示例如下

HTTP/1.1 201 Create
{
  "blog": '{
    "blogID":01,
    "blogTitle":"title",
    "content":"content"
    }',
    "link":"https:blogexample.com/myblog/01",
    "createTime":"Fri, 12 Oct 2012 23:33:14 GMT"
  "documentation_url": "https://developer.blogexample.com"
}

更新博客

更新博客和发布博客类似，但请求时需要提供的指令为PUT指令，提供的参数包括要更新的内容和文章的ID

请求如下：PUT /:username/myblog/update

指令示意如下：

curl -i 'https://api.blogexample.com/user1/myblog/update?blogid=01' -d '{"title":"mytitle","content":"content...."}' 

更新成功后返回的字段号为200，表示资源已被更改，资源不存在或修改失败返回的字段号为4XX或5XX，博客修改成功返回资源示例如下

HTTP/1.1 200 OK
{
  "blog": '{
    "blogID":01,
    "blogTitle":"title",
    "content":"content"
    }',
    "link":"https:blogexample.com/myblog/01",
    "updateTime":"Fri, 12 Oct 2012 23:33:14 GMT"
    "wordNum":500
  "documentation_url": "https://developer.blogexample.com"
}