专栏首页吴伟祥RESTful接口入门 转

RESTful接口入门 转

RESTful产生背景

从下面的图片可以看出,当我们需要把相同的数据展示到不同的界面上时,提供一个可以访问后台的接口,前台只负责将数据友好的,华丽的展示出来即可。而不需要为每一个前台都实现很多的后台逻辑。 

设计方法

协议

Web协议,自然用HTTP,但是现在都用安全的HTTPS协议

域名

专门的服务,专门的域名。(这个更适合互联网公司,有Android,iOS,Web浏览器,为一个专门的服务提供一个专门的域名显然更合适)

版本

考虑到兼容之前发布的版本,为每个版本提供不同的数据来源。

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

路径

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

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

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

HTTP动词

对于资源的具体操作类型,由HTTP动词表示。  常用的HTTP动词有下面五个(括号里是对应的SQL命令)。

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

两个不常用的动词

HEAD:获取资源的元数据。
OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

举例:

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:删除某个指定动物园的指定动物

过滤信息(Filtering)

如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。  下面是一些常见的参数。

?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件

参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

状态码(Status Codes)

服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)。

200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。

错误处理(Error handling)

如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。

{
    error: "Invalid API key"
}

返回结果

针对不同操作,服务器向用户返回的结果应该符合以下规范。

GET /collection:返回资源对象的列表(数组)
GET /collection/resource:返回单个资源对象
POST /collection:返回新生成的资源对象
PUT /collection/resource:返回完整的资源对象
PATCH /collection/resource:返回完整的资源对象
DELETE /collection/resource:返回一个空文档

服务器返回的数据格式,应该尽量使用JSON,某些场合非XML不可时再使用XML。

使用方法

由于RESTful接口返回的都是json格式的数据,做好对这些json处理即可。

参考资料:  https://www.zhihu.com/question/28557115/answer/48094438 http://www.ruanyifeng.com/blog/2014/05/restful_api.html

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • Webjar是什么

    wuweixiang
  • IntelliJ IDEA如何导出和导入设置?

    wuweixiang
  • Mac 刪除鍵(delete)這三招你會嗎?大幅加快打字速度 原

    Option + delete(Control + delete),一次刪除一個單詞

    wuweixiang
  • RESTful API设计指南

    在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的...

    lyb-geek
  • [Err] 1418 - This function has none of DETERMINISTIC, NO SQL, or READS SQL DATA in its declaration a

    [Err] 1418 - This function has none of DETERMINISTIC, NO SQL, or READS SQL DATA ...

    互联网金融打杂
  • 【算法】猴子大王

    一群猴子排成一圈,按1,2,…,n依次编号。然后从第1只开始数,数到第m只,把它踢出圈,从它后面再开始数,再数到第m只,在把它踢出去…,如此不停的进行下去,直到...

    苦咖啡
  • Github上获星的最高ML项目

    机器学习作为一个领域,正在以极快的速度发展。Github是全世界都在关注的白板。高质量的代码定期发布在无限的智慧板上。

    代码医生工作室
  • 我的旁门左道

    旁门左道,汉语成语,拼音是páng mén zuǒ dào,原指不正派的宗教派别,借指不正派的学术派别,现泛指不正派的东西。

    谭广健
  • 互联网已死-大数据的未来在哪里?

    大数据的未来在哪里?以BAT为代表的互联网公司之外是否还会有新的互联网巨无霸诞生,基于技术和资本两方面的考虑,几无可能,未来的互联网世界只能是一个几家独大,行...

    数据饕餮
  • 2019年过去一小半了,这些深度学习研究值得一看!

    转眼间2019年已经过去了快一半,这对于日新月异的深度学习技术已经算是很长一段发展时间。Open Data Science在Medium上整理了2019年到现在...

    CDA数据分析师

扫码关注云+社区

领取腾讯云代金券