RESTful API 设计最佳实践

简介:
+关注继续查看

Web API 近几年变得越来越火,而简洁的 API 设计在多后端系统交互应用中也变得尤为重要。通常,会使用 RESTful API 来作为我们的 Web API 。本文介绍了几种简洁 RESTful API 设计的最佳实践。

使用的名词而不是动词

使用名词来定义接口

资源 GET PUT POST DELETE
一组资源的URI,比如http://www.waylau.com/resources/ 列出 URI,以及该资源组中每个资源的详细信息(后者可选)。 使用给定的一组资源替换当前整组资源。 在本组资源中创建/追加一个新的资源。 该操作往往返回新资源的URL。 删除 整组资源。
单个资源的URI,比如http://www.waylau.com/resources/142 获取 指定的资源的详细信息,格式可以自选一个合适的网络媒体类型(比如:XML、JSON等) 替换/创建 指定的资源。并将其追加到相应的资源组中。 把指定的资源当做一个资源组,并在其下创建/追加一个新的元素,使其隶属于当前资源。 删除 指定的元素。

不应该使用动词:

/getAllResources
/createNewResource
/deleteAllResources

GET 方法和查询参数不能改变资源状态

如果要改变资源的状态,使用 PUT, POST 和 DELETE。下面是错误的用 GET 方法来修改 user 的状态:

GET /users/711?activate 或
GET /users/711/activate

使用名词复数

不要混淆名词的单复数。保持简单,只用复数名词定义所有资源。

/cars 代替 /car
/users 代替 /user
/products 代替 /product
/settings 代替 /setting

使用子资源来表达资源间的关系

GET /cars/711/drivers/  返回 711 号 car 的所有 driver 列表
GET /cars/711/drivers/4 返回 711 号 car 的 4 号 driver

使用 HTTP header 来序列化格式

客户端、服务端都需要知道互相之间的通讯格式。这些格式可以定义在 HTTP header 里面:

  • Content-Type:定义了请求格式
  • Accept:定义了接收相应的格式列表

使用 HATEOAS 约束

HATEOAS(Hypermedia as the engine of application state)是 REST 架构风格中最复杂的约束,也是构建成熟 REST 服务的核心。它的重要性在于打破了客户端和服务器之间严格的契约,使得客户端可以更加智能和自适应,而 REST 服务本身的演化和更新也变得更加容易。 在介绍 HATEOAS 之前,先介绍一下 Richardson 提出的 REST 成熟度模型。该模型把 REST 服务按照成熟度划分成 4 个层次:

  • 第一个层次(Level 0)的 Web 服务只是使用 HTTP 作为传输方式,实际上只是远程方法调用(RPC)的一种具体形式。SOAP 和 XML-RPC 都属于此类。
  • 第二个层次(Level 1)的 Web 服务引入了资源的概念。每个资源有对应的标识符和表达。
  • 第三个层次(Level 2)的 Web 服务使用不同的 HTTP 方法来进行不同的操作,并且使用 HTTP 状态码来表示不同的结果。如 HTTP GET 方法来获取资源,HTTP DELETE 方法来删除资源。
  • 第四个层次(Level 3)的 Web 服务使用 HATEOAS。在资源的表达中包含了链接信息。客户端可以根据链接来发现可以执行的动作。

从上述 REST 成熟度模型中可以看到,使用 HATEOAS 的 REST 服务是成熟度最高的,也是推荐的做法。对于不使用 HATEOAS 的 REST 服务,客户端和服务器的实现之间是紧密耦合的。客户端需要根据服务器提供的相关文档来了解所暴露的资源和对应的操作。当服务器发生了变化时,如修改了资源的 URI,客户端也需要进行相应的修改。而使用 HATEOAS 的 REST 服务中,客户端可以通过服务器提供的资源的表达来智能地发现可以执行的操作。当服务器发生了变化时,客户端并不需要做出修改,因为资源的 URI 和其他信息都是动态发现的。

下面是一个 HATEOAS 的例子:

{
  "id": 711,
  "manufacturer": "bmw",
  "model": "X5",
  "seats": 5,
  "drivers": [
   {
    "id": "23",
    "name": "Stefan Jauker",
    "links": [
     {
     "rel": "self",
     "href": "/api/v1/drivers/23"
    }
   ]
  }
 ]
}

提供过滤、排序、字段选择、分页

过滤:

GET /cars?color=red 
GET /cars?seats<=2 

排序:

GET /cars?sort=-manufactorer,+model

字段选择:

GET /cars?fields=manufacturer,model,id,color

分页:

GET /cars?offset=10&limit=5

API 版本化

版本号使用简单的序号,并避免点符号,如2.5等。正确用法如下:

/blog/api/v1

充分使用 HTTP 状态码来处理错误

HTTP状态码(HTTP Status Code)是用以表示网页服务器 HTTP 响应状态的3位数字代码。它由 RFC 2616 规范定义的,并得到 RFC 2518、RFC 2817、RFC 2295、RFC 2774、RFC 4918 等规范的扩展。

在设计 API 处理错误时,应该充分使用 HTTP 状态码,而不是简单的抛出个 “500 – Internal Server Error(内部服务器错误)”

所有的异常都应该有个错误的 payload 作为映射,下面是一个例子:

{
  "errors": [
   {
    "userMessage": "Sorry, the requested resource does not exist",
    "internalMessage": "No car found in the database",
    "code": 34,
    "more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
   }
  ]
}

参考引用

目录
相关文章
|
1天前
|
API
【Express】—get请求参数 restful API
【Express】—get请求参数 restful API
【Express】—get请求参数 restful API
|
9天前
|
JSON 监控 测试技术
RESTful API设计与实现在员工行为监控系统中的数据交互接口(Go语言)
在现代企业环境中,对员工行为进行监控已经成为确保组织安全和合规性的重要手段。为了提高监控系统的效率和可靠性,自动化测试在系统开发过程中发挥着关键作用。本文将探讨在员工行为监控系统开发中采用JUnit进行自动化测试的实际应用,并通过代码示例演示其工作原理。
41 1
|
13天前
|
设计模式 Java API
使用Spring框架创建一个RESTful API,实现学生信息的管理,包括资源的创建、读取、更新和删除。
在当今的Web应用程序开发中,RESTful API(Representational State Transferful Application Programming Interface)变得越来越重要。Spring框架提供了强大的工具和功能,以便轻松创建、读取、更新和删除(CRUD)资源。在这篇文章中,我们将深入探讨如何使用Spring框架创建一个RESTful API,并通过一个完整的示例演示。
|
13天前
|
前端开发 Java API
什么是RESTful API,Spring MVC如何支持RESTful架构
RESTful API(Representational State Transfer)是一种基于HTTP协议的软件架构风格,用于设计网络应用程序的API。它强调使用标准的HTTP方法(GET、POST、PUT、DELETE等)来进行资源的操作,以及使用URI来标识资源。RESTful API的设计目标是简单、可扩展、易于理解和使用。
|
14天前
|
JSON API 数据格式
使用Python构建RESTful API:Flask和FastAPI的对比与实践
在现代Web开发中,构建RESTful API是一项常见任务。Python提供了多个框架来简化这个过程,其中Flask和FastAPI是两个备受欢迎的选择。本文将对比Flask和FastAPI,并通过实际示例展示它们的用法和优势。
|
1月前
|
前端开发 Java API
# Spring MVC与RESTful API:如何设计高效的Web接口
# Spring MVC与RESTful API:如何设计高效的Web接口
29 0
|
1月前
|
XML 前端开发 JavaScript
【RESTful API的组成部分】
【RESTful API的组成部分】
|
1月前
|
Oracle 关系型数据库 API
C# LIS检验系统源码,接口技术:RESTful API + Http+WCF
LIS检验系统一种专门用于医院化验室的计算机系统,它致力于提高医院化验室的工作效率和检测准确率。LIS系统由多个子系统组成,包括样本管理系统、质控系统、检验结果管理系统、报告管理系统等。体系结构:Client/Server架构 SaaS模式 客户端:WPF+Windows Forms 服务端:C# +.Net 数据库:Oracle 接口技术:RESTful API + Http+WCF
|
2月前
|
存储 JSON API
OData API 和 Restful API 这两个概念的区别和联系
OData API 和 Restful API 这两个概念的区别和联系
27 0
|
2月前
|
存储 Web App开发 Java
使用 jMeter 对需要 User Authentication 的 Restful API 进行并发负载测试
使用 jMeter 对需要 User Authentication 的 Restful API 进行并发负载测试
43 0
热门文章
最新文章
相关产品
云迁移中心
推荐文章
更多