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

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

name

method

api

获取图书信息

get

/v2/book/:id

用户收藏某本图书

post

/v2/book/:id/collection

用户修改对某本图书的收藏

put

/v2/book/:id/collection

用户删除对某个图书的收藏

delete

/v2/book/:id/collection

  • 另外,在一些不符合curd的情况下,使用 post。
  • 把动作转换成资源 比如,上述接口中,用户收藏某本书对外暴露的接口是”/v2/book/:id/collection”,收藏动作通过post方法来展现,而不直接写着api中,collection “收藏”,名次,动作直接转换成了资源。

4.选择合适的状态码

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

  • 2xx: 请求正常处理并返回
  • 3xx: 重定向
  • 4xx: 客户端请求有错误
  • 5xx: 服务端请求有错误

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

状态码

含义

说明

200

ok

请求成功

201

created

创建成功

202

accepted

更新成功

400

bad request

请求不存在

401

unauthorized

未授权

403

forbidden

禁止访问

404

not found

资源不存在

500

internal server error

内部错误

5.使用通用的错误码

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

错误码

错误信息

含义

999

unknow_v2_error

未知错误

1000

need_permission

需要权限

1001

uri_not_found

资源不存在

….

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

6. 安全

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

  • 使用https
  • 使用jwt验证
  • 使用参数签名,防止参数被篡改。
  • 使用权限验证,shiro ,或者自己建数据库(用户、角色、权限)

7.api文档

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

8.参考资料

本文参考了以下的资料:

豆瓣api

理解restful架构

restful introduction

跟着github学习restful api设计

REST接口设计规范

restful api 设计指南

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

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏漏斗社区

工具 | sqlmap系列(四)高级篇

SQLMAP系列终于来到了高级篇,是进阶篇的延续……,本期斗哥将带你走进sqlmap批量扫描的世界。 一.批量化扫描burp的请求日记 01.首先配置burp记...

3739
来自专栏非著名程序员

推荐一款超级下载利器工具,突破网盘的下载限制

目前随着网盘一步一步的关闭或者收费,目前能用的网盘已经不多了,百度网盘目前是为数不多的,暂时没有关闭或者收费的网盘。但是我们都知道,下载网盘里的东西的时候,各种...

902
来自专栏木子昭的博客

Python将md批量转为docx

1576
来自专栏FreeBuf

如何恢复Linux中的误删文件

写在前面的话 在开始教程之前我有必要提醒大家,使用窗口管理器(GUI)删除文件和使用命令行工具(CLI)删除文件这两种方法之间是有区别的。 当我们使用窗口管理器...

2018
来自专栏张戈的专栏

解决wp-super-cache无法(预)缓存问题

突然发现 WP-SUPER-CACHE 无法预缓存,点击【立即加载预缓存】后没有任何效果,并且垃圾回收定时器也失效了,缓存文件全是几天前的,感觉很奇怪! 闲下来...

3215
来自专栏JMCui

Apache solr(二).

上一篇试着进行了solr的安装和配置,以及如何solr的检索,今天试着简单的将solr连接MySQL数据库(才尝试了单表、一对多和多对多的还有待研究) 1、My...

2996
来自专栏何俊林

Android中处理崩溃异常和分析日志的两种思路

前言:在Android开发app中,想要及时了解线上app的运行情况,须要采集样本日志,也就是常说的log,今天由“懂你行云”授权本公众号独家发布,分享他的《处...

24710
来自专栏北京马哥教育

史上最全 Linux 下各文件夹的结构说明及用途介绍

运维行业正在变革,推荐阅读:30万年薪Linux运维工程师成长魔法 linux下各文件夹的结构说明及用途介绍: /bin:二进制可执行命令。 /dev:设备特殊...

40511
来自专栏北京马哥教育

Linux 下各文件夹的结构说明及用途介绍

/home:用户主目录的基点,比如用户user的主目录就是/home/user,可以用~user表示。

770
来自专栏深度学习那些事儿

win10下安装使用pytorch以及cuda9、cudnn7.0

平台: win10(版本1709) CPU:i5-7400 显卡:1060 6G 内容:8G

1599

扫码关注云+社区