1. 编程号首页

【RESTful】RESTful API 接口设计规范 | 示例

编程小号 • • 未分类

【RESTful】RESTful API 接口设计规范 | 示例概念本质：一种软件架构风格核心：面向资源设计的API解决问题：降低开发的复杂性提高系统的可伸缩性例如：设计一套API，为多个终端服务。设计概念和准则网络上的所有事物都可以被抽象为资源每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识所有的操作都是无状态的（本次操作、下次操作、上次操作之间无关系）资源：网络上的一个实体、具体信息。HTTPRESTful与…

最近团队在大规模使用GraphQL ， 关于 GraphQL 和 REST 的比较大家可以点击这里查看
在这里插入图片描述

作者最新打造的 PWA 渐进式Web 应用开发实战课程已经上线（点击访问），帮助你由浅入深更专业地学习。即刻领取邀请码 Se6GGwcQ 获取优惠。高级工程师必备技能，升职加薪靠它！

在这里插入图片描述

概念

本质：一种软件架构风格
核心：面向资源设计的API

解决问题：

  • 降低开发的复杂性
  • 提高系统的可伸缩性

例如：设计一套API，为多个终端服务。

设计概念和准则

  • 网络上的所有事物都可以被抽象为资源
  • 每一个资源都有唯一的资源标识，对资源的操作不会改变这些标识
  • 所有的操作都是无状态的（本次操作、下次操作、上次操作之间无关系）

资源：网络上的一个实体、具体信息。

HTTP

RESTful 与HTTP协议操作无关，但是它是按照HTTP的思想进行设计的，所以有必要知道HTTP

参考官方文档：https://tools.ietf.org/html/rfc2616

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

  • shceme 指定低层使用的协议（如http,https,ftp）
  • host 服务器的IP地址或域名
  • port 服务器端口，默认为80
  • path 访问资源的路径
  • query-string 发送给http服务器的数据，常用于对资源进行筛选操作
  • anchor 锚，链接

请求

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

请求行格式： 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-Version Status-Code Reason-Phrase CRLF

如： HTTP/1.1 200 OK

  • 常用响应状态码（在RESTful 中有重要应用）

200 OK //客户端请求成功

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

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

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

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

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

RESTful 架构与其他架构的区别

API 的开发方式不止一种，另一种比较流行的开发方式是SOAP WebService。

SOAP WebService

WebService 是一种跨编程语言和跨操作系统平台的远程调用技术。其通过HTTP协议发送请求和接收结果时采用XML格式封装，并增加了一些特定的HTTP消息头，这些特定的HTTP消息头和XML内容格式就是SOAP协议。

对比

  • 效率与易用性：SOAP由于各种需求不断扩充其本身协议的内容，导致在SOAP处理方面的性能有所下降。同时在易用性方面以及学习成本上也有所增加。而RESTful API 在请求方法、资源、地址都进行了规范，其最大限度的利用了HTTP最初的应用协议的设计理念。
  • 安全性：RESTful 对于资源型服务器接口比较适合，适合对于效率要求很高，但是对于安全要求不高的场景。SOAP 的成熟性可以给需要提供给多开发语言的，对于安全性的要求较高的接口设计带来便利，你可以在客户端和服务端应用证书进行安全措施。所以关键看应用场景。

使用RESTful

设计RESTful API

  • 资源路径（URI）：RESTful的核心是面向资源，如何规划资源路径很重要

  • HTTP动词(请求方式)：如get,post,delete,put

  • 过滤信息：例如获取资源列表时有分页操作/查询操作，这时要合理分配过滤信息，过滤信息设置太多，有可能会违反RESTful API 关于URI方面的限定。

  • 状态码：当客户端发送一个请求时，服务端应当响应什么状态码

  • 错误处理：如当发现客户端传入的参数有问题时，该返回什么样的状态信息。

  • 返回结果：如POST资源的时候，需要返回一个资源实例；GET资源列表时，需要返回一个资源数组；

资源路径

在RESTful架构中，每个网址代表一个资源，所以网址中不能有动词，只能有名词。一般而言，API中的名词应该使用复数。例如，使用users反映用户资源的URI，而不是使用user。

例如：有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，那么它的资源路径应设计成如下样子。

https://api.example.com/v1/zoos  //动物园资源。使用https协议头;加入v1版本号，因为以后可能会更改api。版本号的加入有两种做法，一种是加入到地址中，另一种是加入到HTTP请求头中;zoos复数

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

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

HTTP动词

对资源的操作有创建、读取、更新、删除(CURD)，由HTTP动词表示。

  • GET ： 从服务器去除资源
  • POST ：在服务器新建一个资源
  • PUT：在服务器更新资源（客户端提供改变后的完整资源，服务端返回完整的更新字段）
  • PATCH：在服务器更新资源（客户端提供改变的属性，服务端返回只发生了更新的字段）
  • DELETE：从服务器删除资源

例如：

POST/zoos : 新建一个动物园
GET/zoos/ID : 获取某个指定动物园的信息
PUT/zoos/ID : 更新某个指定动物园的信息
DELETE/zoos/ID : 删除某个动物园

过滤信息

如果记录数量过多，服务器不可能都将它们返回给用户。这时就需要进行筛选。筛选时，API应该提供一个参数，过滤一下返回的结果。

例如：

?offset = 10 :指定返回记录的开始位置
?page = 2&per_page = 100 :指定第几页，以及每页的记录数
?sortby = name&order = asc :指定返回结果排序，以及排序顺序
?animal_type_id = 1 :指定筛选条件

状态码

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

  • 200 OK 服务器成功返回用户请求的数据
  • 201 CREATED 新建或修改数据成功
  • 204 NO CONTENT 删除数据成功
  • 400 BAD REQUEST 用户发出的请求有错误
  • 401 Unauthorized 表示用户没有认证，无法进行当前操作
  • 403 Forbidden 表示用户的访问是被禁止的
  • 422 Unprocesable Entity 当创建一个对象时，发生一个验证错误。例如创建用户资源时需要用户名、密码，而前端只提供用户名字段，那么就要返回一个422 状态码，并返回错误信息：”密码不能为空“
  • 500 INTERNAL SERVER ERROR 服务器内部错误，此时服务端无法处理任何请求。

错误处理

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

{
  "error":"参数错误"
}

返回结果

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

  • GET/collections: 返回资源对象的列表（数组）
  • GET/collections/identity : 读取资源时，传入标识符(identity),服务端返回标识符指定的单个资源对象
  • POST/collections : 返回新生成的资源对象
  • PUT/collections/identity : 返回完整的资源对象
  • PATCH/collections/identity : 返回被修改的属性
  • DELETE/collections/identity : 返回一个204状态码和空响应体

DHC Client 用于测试API

  • 安装DHC 谷歌浏览器插件：

名为： 基于REST的Web服务客户端
先下载： http://chromecj.com/web-development/2015-03/401.html

或在谷歌商店 ：https://chrome.google.com/webstore/detail/rest-web-service-client/ecjfcmddigpdlehfhdnnnhfgihkmejin?hl=zh-CN

然后安装。

在这里插入图片描述

本地开发环境搭建

  • 安装PHP环境集成包 XAMPP 或 upupw

  • 添加虚拟主机，以及取消跨站目录限制 httpd-vhosts.conf文件中 找到添加的域名，将php_admin_value xxx这句开头加入井号进行注释
    在这里插入图片描述

  • 添加虚拟主机的本地hosts解析 ： 更改本地hosts文件，添加 127.0.0.1 api.com本地域名解析
    在这里插入图片描述

确认设计要素

项目需求

  • 用户登录、注册
  • 文章发表、编辑、管理、列表

确认设计要素

  • 资源路径： /users , /articles
  • HTTP动词： GET,POST,DELETE,PUT
  • 过滤信息： 文章分页筛选
  • 状态码： 200，404，422，403…
  • 错误处理：输出JSON格式错误信息
  • 返回结果：输出JSON数组或JSON对象

数据库设计

在数据库中新建2张表：

  • 用户表： ID、用户名、密码、注册时间
  • 文章表： 文章ID、标题、内容、发表时间、用户ID

添加.htaccess Apache重写文件

在这里插入图片描述

之后就可以在IDE中进行相应的开发编码工作。

当然，处理RESTful API设计思想，还有最近流行的GraphQL，它是一种API查询语言，其将所见即所得的思想引入，能帮助提升开发的体验与应用的性能。（参考：http://graphql.cn/ ）

参考

今天的文章【RESTful】RESTful API 接口设计规范 | 示例分享到此就结束了，感谢您的阅读。

版权声明：本文内容由互联网用户自发贡献，该文观点仅代表作者本人。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如发现本站有涉嫌侵权/违法违规的内容， 请发送邮件至 举报，一经查实，本站将立刻删除。
如需转载请保留出处：https://bianchenghao.cn/11560.html

赞 (0)
编程小号编程小号
0

相关推荐

发表回复

您的电子邮箱地址不会被公开。 必填项已用*标注