RESTFUL如何指导WEB API设计?
博主刚刚接触web开发的时候,写了一个接口 /get_article_info/1 获取id为1的这篇文章的内容,被前辈们看见了,前辈给我说我这个接口设计的不太好啊,不符合RESTFUL规范,当前辈们说出这些话的时候,我很迷惑,我写的接口不能够好好工作吗?能够正常返回内容啊,对于不存在的文章也能够在返回的内容体中提示不存在,而且接口的意思很明确,一看就能明白,这还有什么不好的地方吗?
一、RESTFUL是什么?
RESTFUL是英文单词Representational State Transfer的缩写,翻译成中文就是表现层状态转化,什么是表现层?什么是状态?什么是转化?
表现层可以理解为一种资源,可以是一篇文章,一张图片,一个订单...... 所有网络上的一个实体,都可以说是一个资源,在HTTP协议中,URL就是这种资源的表示。状态和转化应当连在一起理解,这是一个动作,即状态变化,比如新建一篇文章,状态变化是这篇文章从无到有,还有一些其他状态变化,更新,删除,获取等,那在HTTP协议中如何表示这种变化呢?刚好HTTP协议中有一些请求方法,可以和这些操作对应上,GET表示获取,POST表示新建,DELETE表示删除,PUT表示更新。
这样,将HTTP协议的请求方法和URL组合在一起,就能表示对哪个资源进行何种操作,这样的风格就是RESTFUL。
二、 RESTFUL如何指导我们设计API?
核心思想就是HTTP动词 + URL资源,比如获取文章信息 GET /articles, GET是动词,/articles 是名词
1. 动词通常是HTTP的方法
GET: 获取信息
POST: 新建信息
DELETE: 删除信息
PUT: 更新信息
2. 资源必须是名词
已经有了HTTP的方法的动词,URL中,我们就没有必要使用动词了
POST /create_articles
POST /delete_articles
POST /update_articles
上面都是不好的用法,我们应当使用下面这种用法
POST /articles
DELETE /articles/
PUT /articles/
3. 资源最好使用名词的复数,任何情况下都能够适用
/airticles/ 获取id为1的文章内容
/airticles 获取所有文章内容
# 使用单数
/article 获取一篇文章内容?还是所有的文章内容?
4. 避免多级URL
/authors//airticles 获取作者id为5的所有文章
上面换成这种形式更好,也利于扩展
/airticles?author_id=
5. 利用querystring来过滤和筛选
一般情况下一个url很难满足复杂多变的情况,比如分页,过滤,这时候我们应当如何设计?
/airticles/published 这种形式?
不不不,published不是一个资源,而且这种url不宜于扩展
最佳实践应当是下面这种形式
/articles?page= 获取第一页的文章
/articles?published=true 获取已经发布的文章
6. 返回有意义的状态码
HTTP有很多状态码,表示不同的意义,我们应当充分利用这些状态码
尤其是出现错误时,不要返回200,意义很不明确
一般成功请求后返回的状态码
GET: OK
POST: Created
PUT: OK
DELETE: No Content
其他状态码信息
1xx:相关信息
2xx:请求成功
3xx:重定向
4xx:客户端错误
5xx:服务器端错误
2xx状态码表示成功
200 OK 请求成功
201 Created 请求成功,并创建了资源
202 Accepted 请求接受,但未处理完成,一般用于异步处理
204 No Content 请求处理成功,但未返回内容,一般用于DELETE请求成功
3xx状态码表示重定向
301 Moved Permanently 永久重定向
302 Found 暂时重定向
4xx状态码表示客户端错误
400 Bad Request 错误请求,服务器不理解请求,没做任何处理
401 Unauthorized 未认证
403 Forbidden 用户通过了认证,但是没有权限
404 Not Found 没有发现请求的内容
405 Method Not Allowed 不允许的请求方法
5xx状态码表示服务端错误
500 Internal Server Error 服务器内部错误,无法完成请求
503 Service Unavailable 服务不可用
三、总结
RESTFUL就是一种规范,我们不遵循这种规范也能够写出可用的代码,但是遵循这种规范却能给我们带来更多的好处,API设计更加可读,与其他人交流也能够很方便。现在让我看看我刚刚接触web接口开发时的设计,真的是不太好啊,URL信息太重复,错误的返回状态不明确,全是200。
参考文章:https://blog.florimond.dev/restful-api-design-13-best-practices-to-make-your-users-happy
RESTFUL如何指导WEB API设计?的更多相关文章
- 我所理解的RESTful Web API [设计篇]
<我所理解的RESTful Web API [Web标准篇]>Web服务已经成为了异质系统之间的互联与集成的主要手段,在过去一段不短的时间里,Web服务几乎清一水地采用SOAP来构建.构建 ...
- Rest(Restful)风格的Web API跟RPC风格的SOAP WebService--这些名词都啥意思?
经常看到这些词汇,也有baidu或google过,但记忆里总是模糊,不确定,以至于别人问及的时候,总说不清楚.开篇随笔记录下.大家有补充或者意见的尽请留文. 本文顺序: 一.Rest(Restful) ...
- Web API 设计摘要
近期读了一本微电子书 Brian Mulloy 所著<Web API Design>感觉颇多收获,特对其内容做了个整理摘要以便回想其观点精华以指导日常工作中的设计思路. 本文主要讲述 We ...
- GOTO Berlin: Web API设计原则
在邮件列表和讨论区中有很多与REST和Web API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver Wolf在GOTO Berlin大会上开始自己的 ...
- Web API设计
Web API设计经验与总结 在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段,各种 Web服务几乎都采用REST风格的Web Api来构建. 通过Http协议的形式来. ...
- Web API设计方法论
英文原文:A Web API Design Methodology 为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定 ...
- Web API设计方法论--比较完整的web api 开发过程
为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web上维护 ...
- Web API 设计
Web API 设计 The Design of Web APIs free online ebook https://www.manning.com/books/the-design-of-web- ...
- 我所理解的RESTful Web API [设计篇]【转】
原文:http://www.cnblogs.com/artech/p/restful-web-api-02.html <我所理解的RESTful Web API [Web标准篇]>Web服 ...
随机推荐
- 每天3分钟操作系统修炼秘籍(6):Idle进程
点我查看秘籍连载 CPU的归属:Idle进程 操作系统并不总是繁忙.例如个人PC上任务比较轻,多数时候都无法充分利用CPU,导致CPU处于空闲状态.但CPU既然通电了,它就得运行,那么在它没有任务需要 ...
- C# -- RSA加密与解密
1. RSA加密与解密 -- 使用公钥加密.私钥解密 public class RSATool { public string Encrypt(string strText, string st ...
- Pull Request 工作流——更高效的管理代码
目录 Pull Request 工作流--更高效的管理代码 1.问题 2.解决方案 3.Git分支流管理代码具体实施 3.1本地分支操作管理 3.1.1查看分支 3.1.2创建分支 3.1.3切换分支 ...
- tomcat修改使用指定的jdk版本
linux安装的jdk1.6,无法满足当前tomcat项目使用,所以需要指定为更高版本的jdk. 主要修改tomcat bin目录下的catalina.sh和setclasspath.sh文件 添加内 ...
- QT程序自启动
故事背景:最近涉及到客户端更新自启动的一个问题,客户端检测到自己要更新,弹出一个更新界面,然后退出旧版本,启动新版本 技术调研:QProcess 直接上代码吧 qApp->quit(); QPr ...
- diango中的MTV——FBV/CBV以及装饰器的复用问题解决
MVC M: model 模型 与数据库交互 V: view 视图 HTML C:controller 控制器 流程 和 业务逻辑 MTV M:model ORM T:template 模板 HTML ...
- Mac下搭建Cocos2d-x-3.2的开发环境
配置:OS X 10.9.4 + Xcode 6.0 + Cocos2d-x-3.2 摘要:本文目标为在Xcode成功运行HelloWorld程序. 一.下载必要项 1.从官网下载Cocos2d-x- ...
- unittest---unittest简单介绍
说起python的单元测试,第一反应肯定就会是unittest,unittest作为python的标准库,很优秀,也被广泛的用到各个项目,但是你们知道吗?python的单元测试并不只有这一个,还有个p ...
- MATLAB实例:求相关系数、绘制热图并找到强相关对
MATLAB实例:求相关系数.绘制热图并找到强相关对 作者:凯鲁嘎吉 - 博客园 http://www.cnblogs.com/kailugaji/ 用MATLAB编程,求给定数据不同维度之间的相关系 ...
- [考试反思]1113csp-s模拟测试114:一梦
自闭.不废话.写一下低错. T1:觉得信心赛T1不会很恶心一遍过样例直接没对拍(其实是想写完T2之后回来对拍的) 状态也不好,基本全机房都开始码了我还没想出来(skyh已经开T2了).想了40多分钟. ...