大话微服务(三):如何设计Restful API?

本文涉及的产品
服务治理 MSE Sentinel/OpenSergo,Agent数量 不受限
简介:   API的定义取决于选择的IPC通信方式,如果是消息机制(如 AMQP 或者 STOMP),API则由消息频道(channel)和消息类型;如果是使用HTTP机制,则是基于请求/响应(调用http的url),这里我们先简述下RestfulAPI的定义。  设计原则  域名  应该尽量将API部署在专用域名之下,如:  也可以放在主域名下:  版本

  API的定义取决于选择的IPC通信方式,如果是消息机制(如 AMQP 或者 STOMP),API则由消息频道(channel)和消息类型;如果是使用HTTP机制,则是基于请求/响应(调用http的url),这里我们先简述下RestfulAPI的定义。

  设计原则

  域名

  应该尽量将API部署在专用域名之下,如:

  也可以放在主域名下:

  版本

  放入到头信息的Accept中

  制定版本并在版本之间平缓过渡对于设计和维护一套API是个巨大的挑战。所以,最好在设计之初就使用一些方法来预防可能会遇到的问题。

  为了避免API的变动导致用户使用中产生意外结果或调用失败,最好强制要求所有访问都需要指定版本号。请避免提供默认版本号,一旦提供,日后想要修改它会相当困难。

  最适合放置版本号的位置URL中,或者是头信息(HTTP Headers)中在 Accept 段中使用自定义类型(content type)与其他元数据(metadata)一起提交。

  提供 Request-Id

  为每一个请求响应包含一个Request-Id字段,并使用UUID作为该值。通过在客户端、服务器或任何支持服务上记录该值,它能主我们提供一种机制来跟踪、诊断和调试请求。

  路径

  资源名

  在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表格名对应。一般来说,数据库中的表都是同种记录的”集合”(collection),所以API中的名词也应该使用复数。

  举例来说,有一个API提供动物园(zoo)的信息,还包括各种动物和雇员的信息,则它的路径应该设计成下面这样。

  行为(Actions)

  好的末尾不需要为资源指定特殊的行为,但在特殊情况下,为某些资源指定行为却是必要的。为了描述清楚,在行为前加上一个标准的actions:

  如:

  路径和属性名

  为了和域名命名规则保持一致,使用小写字母并用-分割路径名字,例如:

  属性也使用小写字母,但是属性名要用下划线_分割,以便在Javascript中省略引号。 例如:

  支持方便的无id间接引用

  在某些情况下,让用户提供ID去定位资源是不方便的。例如,一个二手手游拍卖平台用户想取得他在Heroku平台app信息,但是这个app的唯一标识是UUID。这种情况下,你应该支持接口通过名字和ID都能访问,例如:

  不要只接受使用名字而放弃了使用id。

  最小化路径嵌套

  在一些有父路径/子路径嵌套关系的资源数据模块中,路径可能有非常深的嵌套关系,例如:

  推荐在根(root)路径下指定资源来限制路径的嵌套深度。使用嵌套指定范围的资源。在上述例子中,dyno属于app,app属于org可以表示为:

  HTTP动词

  对于资源的具体操作类型,由HTTP动词表示。

  常用的HTTP动词有下面五个(括号里是对应的SQL命令):

  一些例子:

  过滤信息

  如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。

  下面是一些常见的参数:

  参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

  响应(Responses)

  状态码

  服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词):

  提供资源的(UU)ID

  在默认情况给每一个资源一个id属性。除非有更好的理由,否则请使用UUID。不要使用那种在服务器上或是资源中不是全局唯一的标识,尤其是自动增长的id。

  生成小写的UUID格式 8-4-4-4-12,例如:

  提供标准的时间戳

  为资源提供默认的创建时间 created_at 和更新时间 updated_at,例如:

  使用UTC(世界标准时间)时间,用ISO8601进行格式化

  在接收和返回时都只使用UTC格式(ISO8601格式的数据)或者使用时间戳。,例如:

  或

  错误处理

  如果状态码是4xx,就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。

  返回结果

  针对不同操作,服务器向用户返回的结果应该符合以下规范。

  保证响应JSON及最小化

  目前为保证响应最小化,一般使用json字符串,并且请求中多余的空格会增加响应大小,而且现在很多的HTTP客户端都会自己输出可读格式("prettify")的JSON。所以最好保证响应JSON最小化,例如:

  而不是这样:

  Hypermedia API

  RESTful API最好做到Hypermedia,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。

  比如,当用户向api.example的根目录发出请求,会得到这样一个文档。

  上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),href表示API的路径,title表示API的标题,type表示返回类型。

  Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计,访问api.github会得到一个所有可用API的网址列表。

  从上面可以看到,如果想获取当前用户的信息,应该去访问api.github/user,然后就得到了下面结果。

  上面代码表示,服务器给出了提示信息,以及文档的网址。

  分享自:

  segmentfault/a/1190000008697972

相关实践学习
基于函数计算快速搭建Hexo博客系统
本场景介绍如何使用阿里云函数计算服务命令行工具快速搭建一个Hexo博客。
目录
相关文章
|
10天前
|
JSON API 数据库
解释如何在 Python 中实现 Web 服务(RESTful API)。
解释如何在 Python 中实现 Web 服务(RESTful API)。
11 0
|
15天前
|
API
阿里云微服务引擎及 API 网关 2024 年 2 月产品动态
阿里云微服务引擎及 API 网关 2024 年 2 月产品动态
|
4天前
|
消息中间件 缓存 API
微服务架构下的API网关性能优化实践
在现代的软件开发中,微服务架构因其灵活性和可扩展性被广泛采用。随着服务的细分与增多,API网关作为微服务架构中的关键组件,承担着请求路由、负载均衡、权限校验等重要职责。然而,随着流量的增长和业务复杂度的提升,API网关很容易成为性能瓶颈。本文将深入探讨API网关在微服务环境中的性能优化策略,包括缓存机制、连接池管理、异步处理等方面的具体实现,旨在为开发者提供实用的性能提升指导。
|
6天前
|
缓存 负载均衡 监控
构建高效微服务架构:API网关的作用与实践
【2月更文挑战第31天】 在当今的软件开发领域,微服务架构已成为实现系统高度模块化和易于扩展的首选方法。然而,随着微服务数量的增加,确保通信效率和管理一致性变得尤为重要。本文将探讨API网关在微服务架构中的核心角色,包括其在请求路由、安全性、负载均衡以及聚合功能方面的重要性。我们将通过具体案例分析,展示如何利用API网关优化后端服务,并讨论实施过程中的最佳实践和常见挑战。
|
7天前
|
缓存 前端开发 API
构建高效可扩展的RESTful API:后端开发的最佳实践
【2月更文挑战第30天】 在现代Web应用和服务端架构中,RESTful API已成为连接前端与后端、实现服务间通信的重要接口。本文将探讨构建一个高效且可扩展的RESTful API的关键步骤和最佳实践,包括设计原则、性能优化、安全性考虑以及错误处理机制。通过这些实践,开发者可以确保API的健壮性、易用性和未来的可维护性。
|
8天前
|
API 开发者 UED
深入探讨RESTful API设计原则及最佳实践
在当今互联网时代,RESTful API已成为各种软件系统之间进行通信的重要方式。本文将从资源定义、URI设计、HTTP方法选择、状态码规范等方面深入探讨RESTful API设计的原则与最佳实践,帮助开发者更好地构建高效、健壮的API。
|
8天前
|
JSON Java API
Springboot项目中如何设计一个规范的统一的Restful API 响应框架?
Springboot项目中如何设计一个规范的统一的Restful API 响应框架?
15 1
|
9天前
|
XML JSON API
通过Flask框架创建灵活的、可扩展的Web Restful API服务
通过Flask框架创建灵活的、可扩展的Web Restful API服务
|
14天前
|
运维 Cloud Native 应用服务中间件
阿里云微服务引擎 MSE 及 API 网关 2024 年 02 月产品动态
阿里云微服务引擎 MSE 面向业界主流开源微服务项目, 提供注册配置中心和分布式协调(原生支持 Nacos/ZooKeeper/Eureka )、云原生网关(原生支持Higress/Nginx/Envoy,遵循Ingress标准)、微服务治理(原生支持 Spring Cloud/Dubbo/Sentinel,遵循 OpenSergo 服务治理规范)能力。API 网关 (API Gateway),提供 APl 托管服务,覆盖设计、开发、测试、发布、售卖、运维监测、安全管控、下线等 API 生命周期阶段。帮助您快速构建以 API 为核心的系统架构.满足新技术引入、系统集成、业务中台等诸多场景需要。
|
15天前
|
JSON 中间件 Shell
使用Python和Flask构建RESTful API
使用Python和Flask构建RESTful API
14 0

相关产品

  • 微服务引擎
  • 服务网格