深入浅出RESTful API设计，小白也能看懂！

Posted 2021-05-23 华为开发者社区

点击“华为开发者社区”轻松关注！

关于RESTful API编写指南、设计规范的文章很多，但大部分文章都没有说清楚在RESTful API设计过程中，每种HTTP请求方法适用于何种场景，使用了这些请求方法后会对客户端和服务端产生何种影响。而有的文章写的太过专业化，让初学者很难理解。

因此，本文本着深入浅出的方法，加上图片解释的形式，为大家介绍一下RESTful API设计过程中应该注意的细节，以及其中的设计原理，让零基础的小白用户也能理解。

什么是RESTful API ？

简单来说，RESTful API 是基于HTTP协议产生的一种相对简单的API设计方案，属于无状态传输。RESTful 的核心是 everything is a “resource”，所有的HTTP action，都应该是相应resource上可以被操作和处理的，而API 就是对资源的管理操作，而这个具体操作是由 HTTP action 指定的。

RESTful API 是目前比较成熟的一套网络应用程序的API设计理论，RESTful API 的出现使前后端设备之间进行交互时可以按照这个设计更规范、更容易交流。

（注：可以把API看做服务器与客户端之间进行连接的一个接口。客户端可以从API这个入口获取、修改服务器里面的资源。）

HTTP协议语义使用方法

在一个RESTful系统里，客户端向服务端发起索取资源的操作只能通过HTTP协议语义来进行交互。最常用的HTTP协议语义有以下5个：

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

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

• PUT：在服务器更新资源（客户端提供完整资源数据）

• DELETE：从服务器删除资源

• HEAD : 从服务器获取报头信息（不是资源）

一些API设计者在使用这5个HTTP协议请求方法时存在语义混用的情况，某些该用PUT请求的资源，却使用了GET。下面就简单介绍一下每个HTTP动词使用场景和对服务器产生的影响。

【注：通常说到幂等性时，还会说安全性（只读）。GET、HEAD和OPTIONS均被认为是安全的方法，而PUT、POST、DELETE等请求都是不安全的（会修改数据）。】

WEB服务接收与返回的互联网资源类型

客户端与服务端进行交互响应时，需要规定双方能够接受何种类型的媒体表现形式，最常见的以application开头的媒体格式类型有：

• application/json： JSON数据格式

• application/xhtml+xml：XHTML格式

• application/xml： XML数据格式

• application/atom+xml：Atom XML聚合格式    

  
  

 部分小白看到这儿可能就会迷糊：RESTful Api 设计与上面提到的资源类型有何关系？

我们以地下党和接头人对接的场景为例，解释下，什么是资源类型？它和API设计有何关系：

地下党A和接口人B见面，双方约定，以敲三下门作为接头暗号，暗号对了就放行。

(这里敲门、敲三下的约定就类似于RESTful Api设计里面的“HTTP协议”，只有按照这个协议约定，合作才能继续进行。)

听到三声敲门声，双方确定是自己人。事先，双方就已经确定以何种方式与对方交流最新情报：中文？英文？粤语？这些方式必须是对方能接收并破译的形式。

（这里的中文、英文、粤语就类似于客户端和服务器交互时使用的资源类型，API设计中只有使用合理的资源类型，才能让客户端获取到可以读取的资源。）

 怎么样？这么一解释，是不是通俗易懂啦！

API设计原则

1、URL

• URL中应尽量使用名词，尽量避免使用动词；

• 应该尽量将API部署在专用域名之下；

https://api.example.com

• 如果确定 API 很简单，不会有进一步扩展，可以考虑放在主域名下；

https://example.org/api/

• 应该将API 的版本号放入URL，或者将版本号放在HTTP头信息中；

https://api.example.com/v1/

2、路径

路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源，所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的”集合"（collection），所以API中的名词也应该使用复数。

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

• https://api.example.com/v1/zoos

• https://api.example.com/v1/animals

• https://api.example.com/v1/employees

3、找到特定领域的媒体类型，根据特定的领域来设计媒体类型

在《RESTful Web APIs》一书中提及到当你想要发布一个API的时候，首先要做的就是找到一个已有的特定领域特定设计。重复造轮子是没有意义的。

在数据返回格式方面，大部分的网站优先提供Xml、JSON的数据返回，Google定义的GData就是在Atom基础上作了扩展，还有一些网站提供了php的数据返回。

3、其他

• 易拓展性：一个易拓展的API设计方案，可以让你延缓实现功能，因为“如果需要的话，后面再添加也很方便”。不需要的功能就不添加；

• 灵活性：API应该具有足够的灵活性来支持上层UI；

• 可移植性：这个API可以运行在任何操作系统上；

API设计流程

来源于《RESTful Web APIs》一书

 如果你发现小编文章中有说的不对的地方，欢迎在文章下方给我们留言指正哦！

华为开发者社区

在一起 创梦想

官方微博：@华为开发者社区（新浪微博）