设计一个博客网站的 API

设计一个博客网站的 API

1.REST介绍

REST 定义了一组体系架构原则，您可以根据这些原则设计以系统资源为中心的 Web 服务，包括使用不同语言编写的客户端如何通过 HTTP 处理和传输资源状态。 如何考虑使用它的 Web 服务的数量，REST 近年来已经成为最主要的 Web 服务设计模式。 事实上，REST 对 Web 的影响非常大，由于其使用相当方便，已经普遍地取代了基于 SOAP 和 WSDL 的接口设计。博客网站理所当然也是资源型的网站，因此在博客网站的接口设计中，可以使用到REST定义的原则。
下面是使用 HTTP 设计 RESTful API 时的一些主要原则：

1.REST API 围绕资源设计，资源是可由客户端访问的任何类型的对象、数据或服务。
2.每个资源有一个标识符，即，唯一标识该资源的 URI。
3.客户端通过交换资源的表示形式来与服务交互。 （许多 Web API 使用 JSON 作为交换格式。）
4.REST API 使用统一接口，这有助于分离客户端和服务实现。 最常见的统一接口是 GET、POST、PUT、PATCH 和 DELETE。
5.REST API 由表示形式中包含的超媒体链接驱动。

2.统一接口

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

GET

GET 检索位于指定 URI 处的资源的表示形式。 响应消息的正文包含所请求资源的详细信息。 成功的 GET 方法通常返回 HTTP 状态代码 200（正常）。 如果找不到资源，该方法应返回 404（未找到）。

POST

POST 在指定的 URI 处创建新资源。 请求消息的正文将提供新资源的详细信息。 请注意，POST 还用于触发不实际创建资源的操作。
如果 POST 方法创建了新资源，则会返回 HTTP 状态代码 201（已创建）。 新资源的 URI 包含在响应的 Location 标头中。 响应正文包含资源的表示形式。
如果该方法执行了一些处理但未创建新资源，则可以返回 HTTP 状态代码 200，并在响应正文中包含操作结果。 或者，如果没有可返回的结果，该方法可以返回 HTTP 状态代码 204（无内容）但不返回任何响应正文。
如果客户端将无效数据放入请求，服务器应返回 HTTP 状态代码 400（错误的请求）。 响应正文可以包含有关错误的其他信息，或包含可提供更多详细信息的 URI 链接。

PUT

PUT 在指定的 URI 处创建或替换资源。 请求消息的正文指定要创建或更新的资源。
与 POST 方法一样，如果 PUT 方法创建了新资源，则会返回 HTTP 状态代码 201（已创建）。 如果该方法更新了现有资源，则会返回 200（正常）或 204（无内容）。 在某些情况下，可能无法更新现有资源。 在这种情况下，可考虑返回 HTTP 状态代码 409（冲突）。
请考虑实现可批量更新集合中的多个资源的批量 HTTP PUT 操作。 PUT 请求应指定集合的 URI，而请求正文则应指定要修改的资源的详细信息。 此方法可帮助减少交互成本并提高性能。

PATCH

PATCH 对资源执行部分更新。 请求正文包含要应用到资源的一组更改。
客户端可以使用 PATCH 请求向现有资源发送一组修补文档形式的更新。 服务器将处理该修补文档以执行更新。 修补文档不会描述整个资源，而只描述一组要应用的更改。 PATCH 方法的规范 (RFC 5789) 未定义修补文档的特定格式。 必须从请求中的媒体类型推断格式。

DELETE

DELETE 删除位于指定 URI 处的资源。

特定请求的影响应取决于资源是集合还是单个子项。 下表汇总了博客网站下的通常准则。

资源	POST	GET	PUT	DELTE
/user/blog	创建新博客	返回用户信息	修改用户信息	删除用户及其所有博客
/user/blog/blogname	新建博客	返回该博客	修改博客内容	删除该博客

3.架构

所有API访问都是通过HTTPS进行的，并且可以通过访问https://api.blog.com。所有数据都以JSON的形式发送和接收。

curl -i https://api.blog.com/users
HTTP/1.1 200 OK
Server: nginx
Date: Fri, 22 Nov 2019 01:41:23 GMT
Content-Type: application/json; charset=utf-8
Connection: keep-alive
Status: 200 OK
ETag: "a00049ba79152d03380c34652f2cb612"
X-GitHub-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

4.参数与示例

1.登录

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

2.获取博客信息

GET-i https://api.blog.com/user/blog/blogname

获取的结果可能如下图

[
  {
    "id": 207819516,
    "node_id": "MDEwOlJlcG9zaXRvcnkyMDc4MTk1MTY=",
    "name": "设计一个博客网站的API",
    "full_name": "mmdxm/设计一个博客网站的API",
    "private": false,
    "owner": {
      "login": "mmdxm",
      "id": 34512530,
      "node_id": "MDQ6VXNlcjM0NTEyNTMw",
      "gravatar_id": "",
      "url": "https://api.github.com/users/mmdxm",
      "html_url": "https://blog.com/mmdxm",
      "type": "Blog",
      "site_admin": false
    },
    "html_url": "https://api.blog.com/mmdxm/设计一个博客网站的API",
    "description": "学习",
    "fork": false,
    "url": "https://api.blog.com/repos/mmdxm",
    "homepage": null,
    "size": 5389,
    "stargazers_count": 0,
    "watchers_count": 0,
    "has_pages": false,
    "forks_count": 0,
    "mirror_url": null,
    "archived": false,
    "disabled": false,
    "open_issues_count": 0,
    "license": null,
    "forks": 0,
    "open_issues": 0,
    "watchers": 0,
    "default_branch": "master"
  },
]

3.POST
发布私有博客

POST -p https://api.blog.com/user/blog/blogname

发布公开博客

POST https://api.blog.com/user/blog/blogname

4.PUT

PUT https://api.blog.com/user/blog/blogname

5.DELETE

DELETE https://api.blog.com/user/blog/blogname

返回的信息可能如下

{
"blogname": "xxxxx",
"blog_id": "123456",
"delete_type": "forever"
"delete_result": "succeed"
"blog_size": 123456
"blog_age":"365"
}