一、REST简介
REST 是一种基于超媒体构建分布式系统的架构风格。 REST 独立于任何基础协议,并且不一定绑定到 HTTP。 但是,最常见的 REST 实现使用 HTTP 作为应用程序协议 。
HTTP 设计 RESTful API 时的一些主要原则:
- REST API 围绕资源设计,资源是可由客户端访问的任何类型的对象、数据或服务。
- 每个资源有一个标识符,即,唯一标识该资源的 URI。
- 客户端通过交换资源的表示形式来与服务交互。 许多 Web API 使用 JSON 作为交换格式。
- REST API 使用统一接口,这有助于分离客户端和服务实现。 对于基于 HTTP 构建的 REST API,统一接口包括使用标准 HTTP 谓词对资源执行操作。 最常见的操作是 GET、POST、PUT、PATCH 和 DELETE。
- REST API 使用无状态请求模型。 HTTP 请求应是独立的并可按任意顺序发生,因此保留请求之间的瞬时状态信息并不可行。 信息的唯一存储位置就在资源内,并且每个请求应是原子操作。
- REST API 由表示形式中包含的超媒体链接驱动。
基本操作:
- GET
- GET 检索位于指定 URI 处的资源的表示形式。 响应消息的正文包含所请求资源的详细信息。成功的 GET 方法通常返回 HTTP 状态代码 200(正常)。 如果找不到资源,该方法应返回 404(未找到)。
- POST
- POST 在指定的 URI 处创建新资源。服务器为新资源分配 URI,并将该 URI 返回给客户端。 在 REST 模型中,我们经常向集合应用 POST 请求。 新资源将添加到集合中。 还可以使用 POST 请求将待处理数据提交到现有资源,且不创建任何新资源。 请求消息的正文将提供新资源的详细信息。 请注意,POST 还用于触发不实际创建资源的操作。
- PUT
- PUT 在指定的 URI 处创建或替换资源。请求消息的正文指定要创建或更新的资源。客户端指定资源的 URI。请求正文包含资源的完整表示形式。 如果已存在具有此 URI 的资源,则替换该资源。 否则创建新资源(如果服务器支持此操作)。 PUT 请求往往应用到单项资源(例如特定的客户)而不是集合。
- PATCH
- PATCH 对资源执行部分更新。 请求正文包含要应用到资源的一组更改。 客户端指定资源的 URI。这比使用 PUT 更高效,因为客户端只发送更改,而无需发送资源的整个表示形式。
- DELETE
- DELETE 删除位于指定 URI 处的资源。
Version
Current version
媒体类型版本控制, 当客户端应用程序向 Web 服务器发送 HTTP GET 请求时,它应使用 Accept 标头规定它可以处理的内容的格式。 如果 Accept 标头未指定任何已知的媒体类型,则 Web 服务器可以生成 HTTP 406(不可接受)响应消息或返回使用默认媒体类型的消息。
Accept: application/vnd.adventure-blog.v1+json
二、过程操作
Users操作
User Authentication
HTTP基本认证
curl -u "username" localhost:7777/api
用户注册
POST localhost:7777/api/users
POST | DESCIPTION | TYPE |
username | 用户名 | string |
password | 密码 | string |
获取所有用户名
GET localhost:7777/api/users
更新密码
PUT localhost:7777/api/users/username
INPUT | TYPE |
newPassword | string |
删除用户
DELETE localhost:7777/api/users/username
博客操作
获取用户的博客简介
GET localhost:7777/api/blogs/user/username
获取博客详情
GET localhost:7777/api/blogs/blogID
应答结果:
{
"articleID": 1,
"title":"title1",
"href":"localhost:7777/api/blogs/blogID",
"private": false,
"description": "...",
"created_at": "2018-01-01T00:31:50Z",
"updated_at": "2019-01-05T17:58:47Z",
"action":"GET",
"status":"original"
"words": 1234,
"visits": 50,
"content":"article contents...."
}
提交新博客
POST localhost:7777/api/blogs
应答结果:
{
"articleID": 1,
"title":"title1",
"href":"localhost:7777/api/blogs/blogID",
"private": false,
"description": "...",
"created_at": "2018-01-01T00:31:50Z",
"updated_at": "2018-01-01T00:31:50Z",
"action":"POST",
"status":"original"
"words": 1234,
"visits": 0,
"content":"article contents...."
}
修改博客
PUT localhost:7777/api/blogs/blogID
POST | TYPE |
title | string |
content | string |
categories | array of string |
删除博客
DELETE localhost:7777/api/blogs/blogID
应答结果(博客的删除情况):
{
"isDeleted":true / false,
"title":"test",
"id" : 1
}
目录操作
获取所有当前目录
GET localhost:7777/api/categories
创建新目录
POST localhost:7777/api/categories
POST | TYPE |
categoryName | string |
获取一个目录的博客简介
GET localhost:7777/api/categories/categoryID
更新目录的名字
PUT localhost:7777/api/categories/categoryID
POST | TYPE |
categoryName | string |
删除目录
DELETE localhost:7777/api/actegories/categoryID