https://mp.weixin.qq.com/s?__biz=MzU0OTE4MzYzMw==&mid=2247485240&idx=1&sn=b5b9c8c41659d2457282dc7ff54d992e&chksm=fbb28ec6ccc507d0951dc50f1a3ecb2529ab39493293e24139ff28cfcde5f8190fa0598b3641&scene=0&key=f9325dcb38245ddc50a7a927757f2643064b68083481a87914c2e39eaa9d4c359ff6b5e8d4f6a29c50fb7bb0145a45ddc01a770d4bc4a884c8e38b66480ad9b0b7a79b21e7fdcbaae57ee4ee366d9a7f&ascene=1&uin=MjgwMTEwNDQxNg%3D%3D&devicetype=Windows-QQBrowser&version=6103000b&lang=zh_CN&pass_ticket=TQe4Haub6SqYOe6NAx8gRfTg7k5UKFKeGcGwRzqGtzjDX%2Bt%2F5w3wOtRKNju9ZHpe

原创: 帝都羊 架构师小秘圈 昨天
1 你一直在错误的使用http协议

现在微服务真是火的一塌糊涂!大街小巷,逢人必谈微服务,各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务!而作为微服务之间通信的桥梁,Web API的设计就显得非常重要。

Http是目前互联网使用最多的协议,没有之一!但是作为Http协议创始人之一的Roy Fielding认为,过去十年,大家都在错误的使用Http协议。删除一个数据,路径往往是 delete/{id} , 更新一条数据,路径往往被定义为update/{id}。你已经被Roy在心里默默的鄙视了!

Roy Fielding提出了一种用于设计Web服务的架构方法,称为Representational State Transfer(REST)。REST的概念是将API结构分离为操作和资源。使用HTTP方法GET、DELETE、POST和PUT操作资源。

设计糟糕的REST API = 浪费时间!

 

优秀的API就像一位艺术家在舞台上表演,其用户就是观众,能给所有人带来赏心悦目的美感!

2 REST API里面的术语

Resource(资源)是指代表某种东西的对象,它具有一些与之相关的数据,并且可以有一组方法对其进行操作。 例如。 学校,班级和学生是资源,删除,添加,更新是要对这些资源执行的操作。

Collections(集合)是一组资源,例如,211大学是全国211所优质大学的集合。

URL(统一资源定位符)是可以通过其定位资源的路径,并且可以对其执行某些操作。

3 API设计使用名词,而不是动词

例如获取所有学生,可能通过如下api:

/getAllStudents,

增加学生,可能是:/addNewStudent

更新学生,可能是:/updateStudent

删除学生,可能是:/deleteStudent

删除所有学生,可能是:/deleteStudents

获取三好学生,可能是:/getSanHaoStudents

更多操作......等等。

对于不同的操作,会衍生出越来越多的API接口,数量不停的增多,接口将会变得混乱和难以维护。

有没有感觉哪里不对?

URL应仅包含资源(名词)而不包含动作或者动词!增加学生的API路径:/addNewStudent,包含操作addNew以及资源名称Student。

正确的方法是什么?

 

/schools ,是一个很好的例子,不包含任何动作。但是我们怎么告诉服务器,有关学校资源的操作呢,例如增加,删除或者更新学校?

这就是HTTP方法(GET,POST,DELETE,PUT)(也成为动词)扮角色的地方!API接口的资源应始终为复数,如果我们要访问资源的一个实例,我们可以在URL中传递id或者name之类的。

GET 路径 /schools 获取所有的学校

GET 路径 /schools/清华 获取名字叫清华大学的详细信息

DELETE 路径 /schools/清华 从学校列表中,删除清华大学

资源和资源之间可能有父子关系,那又应该如何设计呢?例如学校的学生,下面是一些示例:

 

GET /schools/清华/students  获取清华大学的所有学生

GET /schools/清华/students/张三 获取清华大学名字叫张三的学生的详细信息

DELETE /schools/清华/students/张三 删除清华大学名字叫张三的学生

4 合理利用Http本身的方法

HTTP已定义了几组方法,这些方法指示要对资源执行什么类型的操作。我们制定web接口,要合理利用http的方法!

URL是说白了,就是一个句子,其中资源是名词,HTTP方法是动词。

 

GET 方法从资源请求数据,不应产生任何其他作用。

例如/schools/清华/students,返回所有清华大学的学生

POST方法请求服务器在数据库中创建资源,主要是在提交Web表单时。

/schools/清华/students/张三,在清华大学的学生资源,新增一个张三的学生。

POST是非幂等的,这意味着多个请求将具有不同的效果。

PUT方法请求服务器更新资源或创建资源(如果不存在)。

/schools/清华/students/张三, 对清华大学下的学生资源中,更新或者创建张三。

PUT是幂等的,这意味着多个请求将具有相同的效果。

DELETE方法请求从数据库中删除资源或其实例。

/schools/清华/students/张三,从清华大学的学生集合中,删除学生张三的资源。

5 使用JSON作为通信格式

JSON阅读性更高,扩展性更强,适合各种环境和语言进行解析,现在大的互联网公司,对外提供的API基本都使用JSON。

6 使用HTTP状态码

当客户端通过API向服务器发出请求时,客户端应该知道反馈,无论是失败,成功还是请求错误。 HTTP状态代码是一系列标准化代码,针对http请求的可能会发生的各种情况。 服务器应始终返回正确的状态代码。

很多人喜欢把错误信息放在返回值中,典型的Code和Message,其实比较Low。

下面是Http状态码,可以合理利用处理各种请求反馈,将http自身的错误和服务器内部的错误,有一个很好的区分。

2xx(成功类别)

200 Ok表示GET,PUT或POST成功的标准HTTP响应。

201 Created每当创建新实例时,都应返回此状态代码。 例如,使用POST方法创建新实例时,应始返回201状态代码。

204 No Content表示请求已成功处理,但未返回任何内容。

3xx(重定向类别)

304 Not Modified表示客户端已在其缓存中有响应。 因此无需再次传输相同的数据。

4xx(客户端错误类别)

这些状态代码表示客户端已提出错误请求。

400 Bad Request表示未处理客户端的请求,因为服务器无法理解客户端要求的内容。

401 Unauthorized表示不允许客户端访问资源,并应使用所需凭据重新请求。

403 Forbidden表示请求有效且客户端已通过身份验证,但不允许客户端出于任何原因访问该页面或资源。例如,有时不允许授权客户端访问服务器上的目录。

404 Not Found表示请求的资源现在不可用。

410 Gone表示已移动的请求资源不再可用。

5xx(服务器错误类别)

500内部服务器错误表示请求有效,但服务器完全混淆,并要求服务器提供某些意外情况。

503 Service Unavailable表示服务器已关闭或无法接收和处理请求。大多数情况下,例如服务器正在进行维护。

7 搜索,排序,过滤和分页

所有这些操作都只是对一个数据集的查询。将不会有新的API集来处理这些操作。我们需要使用GET方法API附加查询参数。

下面看几个例子:

GET /schools ? search = 清华大学 在大学集合中,搜索清华大学

GET /schools ? sort = rank_asc 按照升序排列学校

GET /schools ? location = 北京 按照城市对学校过滤

GET /schools ? page=6 获取第六页的学校列表

8 使用版本控制

例如下面两个版本地址:

http://api.yourservice.com/v1/schools/清华

http://api.yourservice.com/v2/schools/清华

在API上加入版本信息可以有效的使用户访问正确的API,v2是新开发功能,开发阶段,让所有用户访问v1,等开发完成统一切到v2。

可以有效的跨版本访问,例如在v2版本,还需要访问v1版本的一些接口

9 总结

1,API接口都用小写

2,使用JSON通信

3,API带版本控制,比如v1,v2

4,使用Token令牌进行鉴权

5,路径中单词连接使用中划线-

6,使用HTTP自身的方法表示增删改查资源, GET:查询,POST:新增,PUT:更新,DELETE:删除

7,合理使用HTTP状态码,200,201,400,401,403,500。比如401表示用户身份认证失败,403表示你验证身份通过了,但是无权限操作资源。

在此,祝大家设计出优秀的Restful API!

如何设计出优秀的Restful API?的更多相关文章

  1. 优秀的Restful API应该是什么样的

    1 你一直在错误的使用http协议 现在微服务真是火的一塌糊涂!大街小巷,逢人必谈微服务,各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务!而作为微服务之间通信的桥梁,Web API的设计就显 ...

  2. 如何设计处优秀的Restful API

    只知道遵规循矩的程序员是假程序员,任何技术都是不断发明创造改进的. 如何设计处优秀的Restful API?  盲目跟风,设计糟糕的Resful API = 浪费时间 ! 不啰嗦,直接进入技术主题: ...

  3. 如何设计出优美的Web API?

    概述 WEB API的应用场景非常丰富,例如:将已有系统的功能或数据开放给合作伙伴或生态圈:对外发布可嵌入到其他网页的微件:构建前后端分离的WEB应用:开发跨不同终端的移动应用:集成公司内部不同系统等 ...

  4. OpenStack设计与实现5——RESTful API和WSGI

    转https://segmentfault.com/a/1190000004361778 Tips:文章为拜读@xingjiarong 后有感而做的分享,先对作者表示感谢,附原文地址:http://b ...

  5. 9个步骤:教你设计出优秀的MMORPG副本关卡

    转自:http://www.gameres.com/664485.html 副本的定义 以一张场景地图为原型,针对单个玩家.队伍或者团队生成的一个实例,包含完整的开启关闭.怪物刷新.进度记录等逻辑. ...

  6. ASP.NET Web API实践系列11,如何设计出优秀的API

    本篇摘自:InfoQ的微信公众号 在设计API的时候考虑的问题包括:API所使用的传输协议.支持的消息格式.接口的控制.名称.关联.次序,等等.我们很难始终作出正确的决策,很可能是在多次犯错之后,并从 ...

  7. 国外干货!6个方法助你设计出优秀的APP

    伟大的设计来源于一致性和细致化,而其实只要有足够的纪律,每个团队都可以实现这一点. 品牌(源码:http://www.jinhusns.com/Products/Download/?type=xcj) ...

  8. 设计糟糕的 RESTful API 就是在浪费时间!

    现在微服务真是火的一塌糊涂.大街小巷,逢人必谈微服务,各路大神纷纷忙着把自家的单体服务拆解成多个Web微小服务.而作为微服务之间通信的桥梁,Web API的设计就显得非常重要. HTTP是目前互联网使 ...

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

    1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...

随机推荐

  1. springboot注解@SpringBootApplication分析

    @SpringBootApplication注解用在Spring Boot的入口类上面,是Spring Boot提供的应用启动相关的注解. 直接上注解的源码: @Target(ElementType. ...

  2. HTTL之初印象

    概述 HTTL (Hyper-Text Template Language) 是一个高性能的开源JAVA模板引擎, 适用于动态HTML页面输出, 可替代JSP页面, 指令和Velocity相似. 简洁 ...

  3. laravel 关联中的预加载

    预加载 当作为属性访问 Eloquent 关联时,关联数据是「懒加载」的.意味着在你第一次访问该属性时,才会加载关联数据.不过,是当你查询父模型时,Eloquent 可以「预加载」关联数据.预加载避免 ...

  4. Arrays.copyOf() 和 System.arrayCopy()分析

    java数组的拷贝四种方法:for.clone.System.arraycopy.Arrays.copyof public class Test1 { public static void main( ...

  5. Oracle查询数据库编码

    select userenv('language') from dual

  6. Laravel 的十八个最佳实践

    本文翻译改编自 Laravel 的十八个最佳实践 这篇文章并不是什么由 Laravel 改编的 SOLID 原则.模式等. 只是为了让你注意你在现实生活的 Laravel 项目中最常忽略的内容.   ...

  7. C# Note14: Editable WPF ListView

    (1)https://stackoverflow.com/questions/5652527/editable-wpf-listview (2)How to: Create a ListView wi ...

  8. C# Note4:XML序列化和反序列化(含加密解密等)

    前言 在项目中,我们经常用到各种配置文件,比如xml文件.binary文件等等,这里主要根据实践经验介绍下xml文件的序列化和反序列化(毕竟最常用). 实践背景:我要做一个用户管理功能,用户账号信息存 ...

  9. WPF中元素拖拽的两个实例

    今天结合之前做过的一些拖拽的例子来对这个方面进行一些总结,这里主要用两个例子来说明在WPF中如何使用拖拽进行操作,元素拖拽是一个常见的操作,第一个拖拽的例子是将ListBox中的子元素拖拽到ListV ...

  10. 洛谷 P1032 子串变换

    题目链接 https://www.luogu.org/problemnew/show/P1032 本题是一道bfs问题,从a串开始,每一步完成替换一对字符串(但是一个一步替换可以将这对字符串替换好几次 ...