RESTful API 设计及应用 REST Representational State Transfer 演讲人：李盛洲 致

Presentation on theme: "RESTful API 设计及应用 REST Representational State Transfer 演讲人：李盛洲 致"— Presentation transcript:

1 演讲人：李盛洲 (@zhonger) 致 谢：@mustard制作
RESTful API 设计及应用 REST Representational State Transfer 演讲人：李盛洲 致 REST即表述性状态传递（英文：Representational State Transfer，简称REST）是Roy Fielding博士在2000年他的博士论文中提出来的一种软件架构风格。它是一种针对网络应用的设计和开发方式，可以降低开发的复杂性，提高系统的可伸缩性。 2018年12月31日 本PPT以署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)使用

2 目录 目 录 一、兴起原因 二、对象存储 三、RESTful API设计原则 四、RESTful API实际案例分析 五、Q&A

3 注意：API与用户的通信协议，总是使用HTTPS协议。
兴起原因 HTTP & HTTPS http https Http + TCP + IP Http + SSL/TLS + TCP + IP 无证书，无加密 需要CA申请证书进行加密 明文传输协议 SSL加密传输协议 80端口 443端口 免费 申请证书需要一定费用 注意：API与用户的通信协议，总是使用HTTPS协议。

4 官网：https://letsencrypt.org/
兴起原因 官网：

5 兴起原因 Web Service Web Service (也叫XML Web Service)，是一种可以接收从Internet或者Intranet上的其它系统中传递过来的请求、轻量级的、独立的通讯技术。 Web Service技术， 能使得运行在不同机器上的不同应用无须借助附加的、专门的第三方软件或硬件， 就可相互交换数据或集成。 Web Service的特点： 使用HTTP协议传输数据 采用XML格式封装数据 (XML是Web Service平台中表示数据的格式，在XML中说明调用远程对象的方法、传递的参数以及服务对象返回的结果。) 本页内容参考自(1) (2)

6 (Extensible Markup Language) (JavaScript Object Notation)
兴起原因 兴起原因一：XML & JSON XML (Extensible Markup Language) JSON (JavaScript Object Notation) 应用广泛，可拓展性强 可读性强，可描述复杂结构 用于标记电子文件使其具有结构化的标记语言 格式简单，易于读写 读写、解析速度快，支持多种语言 传输数据量小，传输速率大大提高 描述复杂结构的能力较弱

7 Web Service有什么地方略显不足？
兴起原因 兴起原因二：多前端与同一后端通信 前端应用层出不穷 后端要与前端应用进行通信 需要一个统一的机制，完成前后端通信，实现数据共享 Web Service有什么地方略显不足？ RESTful API

8 兴起原因 实现一个完整的Web服务包括以下步骤：
◆ Web服务提供者设计实现Web服务，并将调试正确后的Web服务通过Web服务中介者发布，并在UDDI注册中心注册； （发布） ◆ Web服务请求者向Web服务中介者请求特定的服务，中介者根据请求查询UDDI注册中心，为请求者寻找满足请求的服务； （发现） ◆ Web服务中介者向Web服务请求者返回满足条件的Web服务描述信息，该描述信息用WSDL写成，各种支持Web服务的机器都能阅读；（发现） ◆ 利用从Web服务中介者返回的描述信息生成相应的SOAP消息，发送给Web服务提供者，以实现Web服务的调用；（绑定） ◆ Web服务提供者按SOAP消息执行相应的Web服务，并将服务结果返回给Web服务请求者。（绑定） SOAP即简单对象访问协议(Simple Object Access Protocol)，它是用于交换XML（标准通用标记语言下的一个子集）编码信息的轻量级协议 本页内容参考自

9 假如要管理一些用户，那么将用户看作是一种资源
兴起原因 REST协议是面向资源的 假如要管理一些用户，那么将用户看作是一种资源 SOAP是面向服务的 还是管理用户，将对用户的操作看成服务 REST协议 操作 SOAP get /users/{userId} 获取userId对应的user信息 post /users/getUser post /users 创建一个新的user post /users/creatUser put /users/{userId} 更改userId对应的user信息 post /users/updateUser delete /users/{userId} 删除userId对应的user post /users/deleteUser 本页内容参考自

10 S3:Simple Storage Service ------ Object Storage
对象存储 S3:Simple Storage Service Object Storage 对象存储 官网介绍： 对象存储是无层次结构的数据存储方法，通常用于云中。不同于其他数据存储 (英文) 方法，基于对象的存储不使用目录树。各个单独的数据（对象）单元存在于存储池中的同一级别。每个对象都有唯一的识别名称，供应用进行检索。此外，每个对象可包含有助于检索的元数据。 可扩展性：对象存储可容纳几乎任意数量的数据，而无需对数据集进行分区。 高效率：缺少层次结构意味着不会有复杂的目录系统所造成的瓶颈。 可用性：对象存储系统具备一些出色机制，能够确保数据一致性，实现自动数据复制和滚动更新，以及消除宕机情况。 本页内容参考自

11 对象存储

12 对象存储 官网： 开源的类S3服务

13 RESTful API 设计原则 域名 (Domain) 版本 (Version) 应该尽量将API部署在专用域名之下。
例： 如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。 例： 版本 (Version) 应该将API的版本号放入URL中。 例： 本部分内容主要参考自(1) (2)《RESTful Web APIs》

14 URI ：Uniform Resource Identifier URL：Uniform Resource Locator
URL & URI URL & URI URI ：Uniform Resource Identifier URL：Uniform Resource Locator 统一资源标识符 统一资源定位符 举个栗子： 动物住址协议://地球/中国/上海市/宝山区/某大学/东区/计算机楼/504实验室/张三.人 身份证号：

15 RESTful API 设计原则 路径 (Endpoint)
在RESTful架构中，网址 = 协议 + 域名 + 版本号 + 资源(Resource,名词) + HTTP动词 例：有一个API提供学校(school)的信息，当中包含学生和教职员工的信息，那么它的路径应该被设计成这样：

16 RESTful API 设计原则 HTTP 动词 (Verbs) 使用动词来表示资源的具体操作类型，常用的有以下五个：
GET（SELECT）：从服务器取出资源（一项或多项）。 POST（CREATE）：在服务器新建一个资源。 PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。 PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。 DELETE（DELETE）：从服务器删除资源。

17 RESTful API 设计原则 HTTP 动词 (Verbs) GET /schools：列出所有学校
POST /schools：新建一个学校 GET /schools/ID：获取某个指定学校的信息 PUT /schools/ID：更新某个指定学校的信息（提供该学校的全部信息） PATCH /schools/ID：更新某个指定学校的信息（提供该学校的部分信息） DELETE /schools/ID：删除某个学校 GET /schools/ID/students：列出某个指定学校的所有学生 DELETE /schools/ID/students/ID：删除某个指定学校的指定学生

18 RESTful API 设计原则 过滤信息 (Filtering)
?limit=10：指定返回记录的数量 ?offset=10：指定返回记录的开始位置。 ?page=2&per_page=100：指定第几页，以及每页的记录数。 ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。 ?animal_type_id=1：指定筛选条件

19 RESTful API 设计原则 状态码 (Status Codes) 服务器向用户返回的状态码和提示信息。

20 RESTful API 设计原则 返回结果 (Result) 针对不同操作，服务器向用户返回的结果应该符合以下规范。
GET /collection：返回资源对象的列表（数组） GET /collection/resource：返回单个资源对象 POST /collection：返回新生成的资源对象 PUT /collection/resource：返回完整的资源对象 PATCH /collection/resource：返回完整的资源对象 DELETE /collection/resource：返回一个空文档

21 https://developers.douban.com/wiki/?title=guide Github API
RESTful API 实际案例分析 豆瓣应用API Github API 其他建议： （1）API的身份认证应该使用OAuth 2.0框架。 （2）服务器返回的数据格式，应该尽量使用JSON，避免使用XML。 Hypermedia API： Github API

22 上海大学开源镜像站： https://mirrors.shuosc.org Linux软件镜像类 开源软件类
服务推荐 上海大学开源镜像站： Linux软件镜像类 开源软件类 Ubuntu Centos Archlinux RFCs CRAN CTAN CPAN Apache OpenSUSE Openwrt Parrot Zabbix Cygwin Pritunl Mariadb Vim Debian Deepin Gentoo Zerotier brew Anaconda Pypi Ceph Kali Debian-cd Deepin-cd Virtualbox Jenkins KDE GNOME GNU Kali-images Kernel Alpine Mysql Libreoffice Node Ruby Rubygems Deb-multimedia Ubuntu-releases Repoforge Postgresql Mongodb homebrew-bottles homebrew-cask homebrew-core Raspbian Gimp Eclipse Docker-ce Elvish videolan-ftp 上海大学NPM镜像站： 上海大学Pypi镜像站： 上海大学开源社区Git服务： 或者

23 Q & A Q & A

24 Thanks Thanks for listening!