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

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

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

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

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

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

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

兴起原因 实现一个完整的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（标准通用标记语言下的一个子集）编码信息的轻量级协议 本页内容参考自http://blog.csdn.net/yangwenxue_admin/article/details/51059125;

假如要管理一些用户，那么将用户看作是一种资源 兴起原因 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 本页内容参考自https://www.zhihu.com/question/28557115

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

对象存储

对象存储 官网：https://minio.io 开源的类S3服务

RESTful API 设计原则 域名 (Domain) 版本 (Version) 应该尽量将API部署在专用域名之下。 例：https://api.example.com 如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。 例：https://example.org/api/ 版本 (Version) 应该将API的版本号放入URL中。 例：https://api.example.com/v1/ 本部分内容主要参考自(1)http://www.ruanyifeng.com/blog/2014/05/restful_api.html; (2)《RESTful Web APIs》

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

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

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

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：删除某个指定学校的指定学生

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

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

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

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

上海大学开源镜像站： https://mirrors.shuosc.org Linux软件镜像类 开源软件类 服务推荐 上海大学开源镜像站： https://mirrors.shuosc.org 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镜像站： https://npm.shuosc.org 上海大学Pypi镜像站： https://pypi.shuosc.org 上海大学开源社区Git服务：https://git.shuosc.org 或者 https://git.shuosc.cn

Q & A Q & A

Thanks Thanks for listening!