我是如何根据豆瓣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 条评论
登录 后参与评论

相关文章

来自专栏酷玩时刻

CentOS 7更改yum源与更新系统

822
来自专栏前端之心

域名解析详解

我们知道网络通讯基本上是基于TCP/IP的,而TCP/IP以IP地址为基础,而域名仅仅是为了方便人类的记忆而设计的名称,计算机在网络中进行通讯时不能识别域名,只...

2383
来自专栏老安的博客

国内某公有云 linux云主机开机初始化过程分析和他的镜像制作过程

1163
来自专栏后端技术探索

狼厂项目实践:通用检索框架准实时流的设计与实现

检索对实时性的要求很高,不仅是对索引建立、结果召回、策略干扰等核心部分,也包括数据录入的部分。检索的数据流主要包括全量数据与增量数据,其中全量数据是在运行前就已...

591
来自专栏七夜安全博客

python开发ftp服务器

1343
来自专栏魏艾斯博客www.vpsss.net

百度站长工具和 360 站长平台自动推送代码如何安装使用

2925
来自专栏Rainbond开源「容器云平台」

Rainbond插件体系设计简介

1033
来自专栏Java技术栈

两年摸爬滚打 Spring Boot,总结了这 16 条最佳实践

Spring Boot是最流行的用于开发微服务的Java框架。在本文中,我将与你分享自2016年以来我在专业开发中使用Spring Boot所采用的最佳实践。这...

773
来自专栏腾讯云技术沙龙

彭磊:TencentHub的架构实现

TencentHub是一个集Docker镜像、二进制文件、helmcharts于一体的仓库存储服务。那么这一架构技术是如何基于Kubernetes 快速实现wo...

66641
来自专栏逸鹏说道

vs运行时候冒了这个错:无法启动IIS Express Web 服务器~Win10

异常处理汇总-服 务 器 http://www.cnblogs.com/dunitian/p/4522983.html 网站部署之~Windows Server...

2514

扫码关注云+社区