博主刚刚接触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设计?的更多相关文章

  1. 我所理解的RESTful Web API [设计篇]

    <我所理解的RESTful Web API [Web标准篇]>Web服务已经成为了异质系统之间的互联与集成的主要手段,在过去一段不短的时间里,Web服务几乎清一水地采用SOAP来构建.构建 ...

  2. Rest(Restful)风格的Web API跟RPC风格的SOAP WebService--这些名词都啥意思?

    经常看到这些词汇,也有baidu或google过,但记忆里总是模糊,不确定,以至于别人问及的时候,总说不清楚.开篇随笔记录下.大家有补充或者意见的尽请留文. 本文顺序: 一.Rest(Restful) ...

  3. Web API 设计摘要

    近期读了一本微电子书 Brian Mulloy 所著<Web API Design>感觉颇多收获,特对其内容做了个整理摘要以便回想其观点精华以指导日常工作中的设计思路. 本文主要讲述 We ...

  4. GOTO Berlin: Web API设计原则

    在邮件列表和讨论区中有很多与REST和Web API相关的讨论,下面仅是我个人对这些问题的一些见解,并没有绝对的真理,InnoQ的首席顾问Oliver Wolf在GOTO Berlin大会上开始自己的 ...

  5. Web API设计

    Web API设计经验与总结 在移动互联网的时代, Web服务已经成为了异构系统之间的互联与集成的主要手段,各种 Web服务几乎都采用REST风格的Web Api来构建. 通过Http协议的形式来. ...

  6. Web API设计方法论

    英文原文:A Web API Design Methodology 为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定 ...

  7. Web API设计方法论--比较完整的web api 开发过程

    为Web设计.实现和维护API不仅仅是一项挑战:对很多公司来说,这是一项势在必行的任务.本系列将带领读者走过一段旅程,从为API确定业务用例到设计方法论,解决实现难题,并从长远的角度看待在Web上维护 ...

  8. Web API 设计

    Web API 设计 The Design of Web APIs free online ebook https://www.manning.com/books/the-design-of-web- ...

  9. 我所理解的RESTful Web API [设计篇]【转】

    原文:http://www.cnblogs.com/artech/p/restful-web-api-02.html <我所理解的RESTful Web API [Web标准篇]>Web服 ...

随机推荐

  1. Client error attempting to change layout margins of a private view

    从 iOS 11 开始,UINavigationBar 使用了自动布局,左右两边的按钮到屏幕之间会有 16 或 20 的边距. 为了避免点击到间距的空白处没有响应,通常做法是:定义一个 UINavig ...

  2. Beta版本演示

    小组信息 组名:斗地组 组长博客:地址 组内成员: 组员 学号 林涛(组长) 031702616 童圣滔 031702117 林红莲 031702213 潘雨佳 031702214 覃鸿浩 03170 ...

  3. js的动态表格的增删改查思路

    1. 首先我们要知道,动态添加,肯定不是 在页面上写死得,而是通过js调用循环放入到页面上的,我们在写动态表格的时候不要先着急写,我们第一步要做的就是构思,要把自己的逻辑先弄清楚,不然的话,前面是好写 ...

  4. Vue之判断对象是否为空的方法

    1. JSON.stringify(xxx)=='{}' 2. Object.keys(xxx).length==0 验证结果如下:

  5. 【THUPC 2018】赛艇

    Problem Description Lavender.Caryophyllus.Jasmine.Dianthus现在在玩一款名叫"赛艇"的游戏. 这个游戏的规则是这样的: 玩家 ...

  6. SpringBoot系列-整合Mybatis(注解方式)

    目录 一.常用注解说明 二.实战 三.测试 四.注意事项 上一篇文章<SpringBoot系列-整合Mybatis(XML配置方式)>介绍了XML配置方式整合的过程,本文介绍下Spring ...

  7. Jupiter 页面环境下使用pip无法安装(AttributeError: module 'pip' has no attribute 'main')

    异常: AttributeError Traceback (most recent call last) <ipython-input-5-880e5dfa627c> in <mod ...

  8. ribbon客户端负载均衡

    Ribbon简介 参考:https://blog.csdn.net/chengqiuming/article/details/80711168 Ribbon是Netflix发布的负载均衡器,它有助于控 ...

  9. JS---part2课程介绍+part1复习

    part1复习 JavaScript分三个部分: 1. ECMAScript标准----JS基本的语法 2. DOM:Document Object Model 文档对象模型 3. BOM:浏览器对象 ...

  10. Java_枚举Enum基本使用

    特性 在某些情况下,一个类的对象时有限且固定的,如季节类,它只有春夏秋冬4个对象这种实例有限且固定的类,在 Java 中被称为枚举类: 在 Java 中使用 enum 关键字来定义枚举类,其地位与 c ...