我是如何根据豆瓣api来理解Restful API设计的

网友投稿 791 2022-05-29

1.什么是REST

REST全称是Representational State Transfer,表述状态转移的意思。它是在Roy Fielding博士论文首次提出。REST本身没有创造新的技术、组件或服务,它的理念就是在现有的技术之上,更好的使用现有的 web规范。用REST规范的web服务器,能够更好的展现资源,客户端能够更好的使用资源。每个资源都由URI/ID标识。REST本身跟http无关,但是目前http是与它相关的唯一实例。REST有着优雅、简洁的特性,本文是根据豆瓣api来谈谈自己对restful的一些理解。

2.URI规范

URI(Uniform Resource Identifiers) 统一资源标示符

URL(Uniform Resource Locator) 统一资源定位符

URI 的格式:

URI的格式定义如下:   URI = scheme "://" authority "/" path [ "?" query ] [ "#" fragment ]

uri代表的是一种资源,要做到优雅、简洁。

最好在api地址标明版本

比如

https://api.douban.com/v2

关于分隔符“/”,比如:

"/"分隔符一般用来对资源层级的划分,比如: https://api.douban.com/v2/book/1220562 表述了豆瓣api,version2下的图书仓库下的编号为1220562的图书。

URI尽量使用“-”代替下划线“_“。

URI统一使用小写字母

URI不包含文件扩展名

使用?用来过滤资源,比如?limit=10 :指定返回10条记录。

不使用无意义的字符串、数字,要做到简洁。

3.正确使用method

get -只用做资源的读取。

post-通过用作创建一个新的资源。

delete-通过用作资源的删除。

put -通过用作更新资源或者创建资源

head-只获取某个资源的头部信息。

比如 豆瓣图书api:

另外,在一些不符合curd的情况下,使用 post。

把动作转换成资源

比如,上述接口中,用户某本书对外暴露的接口是”/v2/book/:id/collection”,动作通过post方法来展现,而不直接写着api中,collection “”,名次,动作直接转换成了资源。

4.选择合适的状态码

http请求需要返回状态码,约定俗成的状态码能够帮助开发团队提高沟通效率。

2xx: 请求正常处理并返回

3xx: 重定向

4xx: 客户端请求有错误

5xx: 服务端请求有错误

比如豆瓣api返回的状态码说明:

5.使用通用的错误码

通用错误码,具体产品由具体产品api给出。比如豆瓣api:

太多了,只列出几条,具体见豆瓣 api。

6. 安全

这部分内容不属于这篇文章,但是稍微说明下:

使用https

使用jwt验证

使用参数签名,防止参数被篡改。

使用权限验证,shiro ,或者自己建数据库(用户、角色、权限)

7.api文档

接口文档的编写至关重要,最好是写一个在线接口文档。接口文档能够方便团队查阅,减少不必要的沟通。如果对外公开api,api文档的质量直接反应了一个公司的技术水平,甚至一个公司的文化气质。

8.参考资料

本文参考了以下的资料:

豆瓣api

理解restful架构

我是如何根据豆瓣api来理解Restful API设计的

restful introduction

跟着github学习restful api设计

REST接口设计规范

restful api 设计指南

https://mp.weixin.qq.com/s?__biz=MzAxNjk4ODE4OQ==&mid=2247484105&idx=1&sn=73c5f70a2c3301ed4e3170212bdc5d1b&chksm=9bed23bbac9aaaad702c60aee9282eb45a9247e6366bebc5cc4aa9af0819bd3ce80d7021c3ac&scene=21#wechat_redirect

网络安全 HTTP API

版权声明:本文内容由网络用户投稿,版权归原作者所有,本站不拥有其著作权,亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容,请联系我们jiasou666@gmail.com 处理,核实后本网站将在24小时内删除侵权内容。

上一篇:【云图说】第81期 华为云GPU共享型AI容器,让你用得起,用得好,用的放心
下一篇:《TCP/IP详解卷3:TCP事务协议、HTTP、NNTP和UNIX域协议》 —1.8 历史
相关文章