有容云产品设计揭秘 – RESTful API设计理念

有容云是一个高度研发导向的公司。我们的产品涉及容器平台技术的方方面面。采用微服务架构,服务之间由RESTful API来调用,非常易于扩展。

 

本文就是对有容云产品开发实践中遵循的RESTful API的设计原则进行总结,即是一个简明扼要的设计原则总结,也希望能够让读者在工作中碰到同样的技术需求时有更多的参考。 

 

采用RESTful API设计

 

●  拓展性。无状态的RESTful API使拓展变得非常容易。

●  通用性。基于http协议。

●  独立性。每个组件模块能够独立运行和独立更新升级。

●  高效性。能够利用Cache来降低系统延迟。

●  安全性。可以嵌入HTTP安全协议。

●  封装性。封装完好的API设计。

 

采用JSON数据格式

 

●  通用性强。几乎所有语言和客户端都支持JSON。

●  简单易用。JSON数据的格式定义非常简单明了。

●  可读性好。JSON的数据不需要辅助工具就可以基本读懂。

●  扩展性好。JSON数据格式可以随时的添加和改变而不需要改变客户端。

 

定义资源的原则

 

●  只定义资源对象的名词而不是动词。如AppHouse中对于项目的资源定义为/projects, 而不是/GetProjects或者/ProjectsCreate.

●  对于资源的动作由Method来完成。GET/PUT/POST/DELETE

●  用复数来定义资源。保持API的一致。

●  避免过深的层级。可以采用查询参数代替路径中的实体导航。

●  定义资源时提供的是能力而不是应用。应用由客户端自己来定义,不要试图去帮助客户端来定义应用。

 

定义method操作的原则

 

 

●  GET/PUT/DELETE为幂等操作(idempotent)。POST为非幂等操作。

●  PUT操作资源时必须提供资源的全部信息。

●  尽量采用POST,因为非幂等操作支持部分更新,比较灵活并且能够降低数据传输量。

 

定义媒体类型(Media Type)的原则

 

●  不要忽略在Request的HTTP-Header中指定Accept 定义可接受的响应格式,在Response的HTTP-Header中指定Content-Type定义数据格式。

●  Accept中指定多种媒体格式时,最先声明的有最高优先级。

●  可以自定义MediaType。

 

定义域名和API版本

 

●  API尽量部署在专有域名之下,如api.youruncloud.com

● API的版本号应该放入URL,如https://api.youruncloud.com/v1/,而不是HTTP-Header.application/json; application&v1

 

定义参数

 

 

Hypermedia API

 

和网上许多文章提倡Hypermedia API的Rest设计相反,我并不提倡这种设计。尤其是针对企业级的平台级产品。这种设计增加了客户端和服务端设计的复杂性,而复杂性是和Rest相违背的。具体参见这篇文章

https://jeffknupp.com/blog/2014/06/03/why-i-hate-hateoas/

 

状态码及详情设计

 

包含错误码,错误信息,详情链接。

{

  "code": 2100,

  "message": "XXX is not a validpassword.",

  "more_info": "https://api.youruncloud.com/docs/errors/2100",

 }

 

 

分享:有容云产品设计揭秘 – RESTful API设计理念

有容云-构筑企业容器云 www.youruncloud.com

温馨提示

对Docker容器技术或容器生产实施感兴趣的朋友欢迎加群讨论。我们汇集了Docker容器技术落地实施团队精英及业内技术派高人,在线为您分享Docker技术干货。我们的宗旨是为了大家拥有更专业的平台交流Docker实战技术,我们将定期邀请嘉宾做各类话题分享及回顾,共同实践研究Docker容器生态圈。

加微信群方法:

1.关注【有容云】公众号

2.留言”我要加群”

QQ群号:454565480

有容云微信二维码