资源路径（URI）

用户表

ID、用户名、密码、注册时间

文章表

文章 ID、标题、内容、发表时间、用户 ID

确认设计要素

• 资源路径：/users、/articles

• HTTP 动词：GET、POST、DELETE、PUT

• 过滤信息：文章的分页筛选

• 状态码：200、404、422、403

• 错误处理：输出 JSON 格式错误信息

• 返回结果：输出 JSON 数组或 JSON 对象

项目需求

• 用户登录、注册

• 文章发表、编辑、管理、列表

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范：

• GET /collections：返回资源对象的列表（数组）

• GET /collections/identity：返回单个资源对象

• POST /collections：返回新生成的资源对象

• PUT /collections/identity：返回完整的资源对象

• PATCH /collections/identity：返回被修改的属性

• DELETE /collections/identity：返回一个空文档
  

错误处理

如果状态码是 4xx 或者 5xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可

{
    “error'”: “参数错误”
}

状态码

服务器向用户返回的状态码和提示信息，使用标准 HTTP 状态码。

• 200 OK 服务器成功返回用户请求的数据，该操作是幂等的。

• 201 CREATED 新建或修改数据成功。

• 204 NO CONTENT 删除数据成功。

• 400 BAD REQUEST 用户发出的请求有错误，该操作是幂等的。

• 401 Unauthorized 表示用户没有认证，无法进行当前操作。

• 403 Forbidden 表示用户访问是被禁止的。

• 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。

• 500 INTERNAL SERVER ERROR 服务器发生错误，用户将无法判断发出的请求是否成功。

过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API 应该提供参数，过滤返回结果。

举例

• ?offset=10：指定返回记录的开始位置。

• ?page=2&per_page=100：指定第几页，以及每页的记录数。

• ?sortby=name&order=asc：指定返回结果排序，以及排序顺序。
  

• ?animal_type_id=1：指定筛选条件

HTTP 动词

对于资源的操作（CURD），由 HTTP 动词（谓词）表示。

• GET：从服务器取出资源（一项或多项）。

• POST：在服务器新建一个资源。

• PUT：在服务器更新资源（客户端提供改变后的完整资源）

• PATCH：在服务器更新资源（客户端提供改变的属性）。

• DELETE：从服务器删除资源。

举例

• POST /zoos：新建一个动物园

• GET /zoos/ID：获取某个指定动物园的信息

• PUT /zoos/ID：更新某个指定动物园的信息

• DELETE /zoos/ID：删除某个动物园

资源路径

在 RESTful 架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词。一般来说 API 中的名词应该使用复数。

举例

举例来说，有一个 API 提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos //动物园资源

https://api.example.com/v1/animals //动物资源

https://api.example.com/v1/employees //雇员资源

如何设计 RESTful API

• 资源路径（URI）

• HTTP 动词

• 过滤信息

• 状态码

• 错误处理

• 返回结果
  

安全性

RESTful 对于资源型服务接口来说很合适，同时特别适合对于效率要求很高，但是对于安全要求不高的场景。

SOAP 的成熟性可以给需要提供给多开发语言的，对于安全性要求较高的接口设计带来便利。所以我觉得纯粹说什么设计模式将会占据主导地位没有什么意义，关键还是看应用场景。

效率和易用性

SOAP 由于各种需求不断扩充其本身协议的内容，导致在 SOAP 处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所

增加。

RESTful 由于其面向资源接口设计以及操作抽象简化了开发者的不良设计，同时也最大限度的利用了 Http 最初的应用协议设计理念。

SOAP WebService

WebService 是一种跨编程语言和跨操作系统平台的远程调用技术。

WebService 通过 HTTP 协议发送请求和接收结果时采用 XML 格式封装，并增加了一些特定的 HTTP 消息头，这些特定的 HTTP 消息头和 XML 内容格式就是 SOAP 协议。

HTTP 协议 - 响应

• 组成格式：状态行、消息报头、响应正文

• 状态行

  HTTP-Version Status-Code Reason-Phrase CRLF

  HTTP/1.1 200 OK

• 常用状态码
  

  200 OK //客户端请求成功
  

  400 Bad Request //客户端请求有语法错误，不能被服务器所理解

  401 Unauthorized //服务器收到请求，但是拒绝提供服务

  404 Not Found //请求资源不存在

  500 Internal Server Error //服务器发生不可预期的错误

  503 Server Unavailable //服务器当前不能处理客户端的请求

HTTP 协议 - 请求

• 组成格式：请求行、消息报头、请求正文

• 请求行

  格式如下：Method Request - URI HTTP - Version CRLF

• 举例

  GET HTTP/1.1 CRLF

• 请求方法
  

  GET 请求获取 Request-URI 所标识的资源

  POST 在 Request-URI 所标识的资源后附加新的数据

  HEAD 请求获取由 Request-URI 所标识的资源的响应消息报头
  

  PUT 请求服务器存储一个资源，并用 Request-URI 作为其标识
  

  DELETE 请求服务器删除 Request-URI 所标识的资源

  OPTIONS 请求查询服务器的性能，或者查询与资源相关的选项和需求

HTTP 协议 - URL

• HTTP 是一个属于应用层的协议，特点是简捷、快速。

• schema://host[:port]/path[?query-string][#anchor]

  • scheme：指定低层使用的协议（例如：http, https, ftp）

  • host：服务器的 IP 地址或者域名

  • port：服务器端口，默认为 80

  • path：访问资源的路径

  • query-string：发送给 http 服务器的数据

  • anchor：锚
    

资源

什么是资源？

所谓“资源”，就是网络上的一个实体，或者说是网络上的一个具体信息。

设计概念和准则

• 网络上的所有事物都可以被抽象为资源。

• 每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识。

• 所有的操作都是无状态的。

RESTful 是什么

本质：一种软件架构风格

核心：面向资源

解决的问题

• 降低开发的复杂性

• 提高系统的可伸缩性

如何设计RESTful API

设计资源路径：网址代表一种资源，网址中不能出现动词，只能有名词，一般来说名词应该使用复数。

设计RESTFul API 六要素

RESTful面向资源设计API， 一种软件架构风格

soap WebService接口

常用状态码

每种http 请求方式，对应一个php方法：

1、POST /url 创建  insert ，非幂等
2、DELETE /url/xxx 删除  delete  幂等
3、PUT /url/xxx 更新 update 幂等
4、GET /url/xxx 查看 一条或列表 select 幂等

幂等的意味着对同一URL的多个请求应该返回同样的结果

创建数据，要返回数据信息