RESTful API设计

该文章发布于 ,归类于 其它 0 条评论

今天听到一个陌生的名词“RESTful API”,后来在网上求解了一下,发现原来是请求接口的意思。

对于前端开发人员,很多时候需要与后端的数据进行对接,而这个对接的数据请求的接口,便是本文的主题。

什么是RESTful API?

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

(这里就可以把API看做是服务器与客户端之间进行连接的一个接口,客户端可以从API这个入口获取、修改服务器里面的资源)

HTTP协议语义使用方法

GET(SELECT):从服务器取出资源(一项或多项)。
POST(CREATE):在服务器新建一个资源。
PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
DELETE(DELETE):从服务器删除资源。
HEAD : 从服务器获取报头信息(不是资源)

一些例子

GET /zoos:列出所有动物园
POST /zoos:新建一个动物园
GET /zoos/ID:获取某个指定动物园的信息
PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
DELETE /zoos/ID:删除某个动物园
GET /zoos/ID/animals:列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物

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

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

application/json: JSON数据格式

application/xhtml+xml:XHTML格式

application/xml: XML数据格式

application/atom+xml:Atom XML聚合格式

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的数据返回。

4、其他

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

灵活性:API应该具有足够的灵活性来支持上层UI;

可移植性:这个API可以运行在任何操作系统上;

API应该对程序员友好,并且在浏览器地址栏容易输入;

文章参考地址:https://sanwen8.cn/p/2ddcbVD.html

相关文章