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

相关文章

来自专栏13blog.site

Spring+SpringMVC+MyBatis+easyUI整合进阶篇(一)设计一套好的RESTful API

写在前面的话 看了一下博客目录,距离上次更新这个系列的博文已经有两个多月,并不是因为不想继续写博客,由于中间这段时间更新了几篇其他系列的文章就暂时停止了,如今已...

2885
来自专栏BestSDK

5个不为人知的Java API使用技巧

程序员都喜欢使用API!例如为app应用构建API或作为微服务架构体系的一部分。当然,使用API的前提是能让你的工作变得更轻松。为了简化开发和提高工作效率所作出...

3214
来自专栏跟着阿笨一起玩NET

C#远程调用技术WebService修炼手册

3.1、Webservice是如何实现远程调用?三要素在webservice的作用?

942
来自专栏散尽浮华

Centos7下部署分布式跟踪工具Pinpoint的操作记录

一、Pinpoint简单介绍 Pinpoint是一款对Java编写的大规模分布式系统的APM工具,有些人也喜欢称呼这类工具为调用链系统、分布式跟踪系统。一般来说...

1272
来自专栏Java进阶架构师

IntelliJ IDEA 内存优化最佳实践

原文链接::http://blog.oneapm.com/apm-tech/426.html

602
来自专栏Java学习123

ESB企业服务总线

38414
来自专栏ImportSource

CQRS距你有多远?

前面两集(微服务业务开发三个难题-拆分、事务、查询(上),微服务业务开发三个难题-拆分、事务、查询(下))翻译了Chris的大作。为了保证原意不跑偏同时通俗易懂...

4198
来自专栏魏琼东

AgileEAS.NET SOA 中间件平台5.2版本下载、配置学习(一):下载平台并基于直连环境运行

一、前言      AgileEAS.NET SOA 中间件平台是一款基于基于敏捷并行开发思想和Microsoft .Net构件(组件)开发技术而构建的一个快速...

2137
来自专栏全华班

重新认识你认识的Hibernate

Hibernate估计大家已经用过很多年了吧,好多同学说用过Hibernate,不需要你来讲,但再仔细想想,你能告诉我Hibernate是什么吗? 今天带大家重...

3414
来自专栏圆方圆学院精选

【戴嘉乐】(进阶)基于IPFS和Ngrok构建自维护资源网关

上篇文章《【应用】(入门)基于IPFS和Ngrok构建自维护资源网关》,我们通过Ngrok为IPFS节点配置HTTP Tunnels,充分利用了其NAT穿越的特...

981

扫码关注云+社区