RESTful最佳实践

哲学

  • 不要为了RESTful而RESTful
  • 在能表达清楚的情况下，简单就是美

接口路径设计

接口设计原则

URI指向的是唯一的资源对象

示例: 指向ID为yanbo.ai的Account对象

GET http://~/$version/accounts/yanbo.ai

URI可以隐式指向唯一的集合列表

示例: 隐式地指向trades list 集合

GET http://~/$version/trades/(list)等同于GET http://~/$version/trades

聚合资源必须通过父级资源操作

示例: Profile是User的聚合资源，User有一个唯一且私有的Profile资源，只能通过User操作Profile。

更新user_id为123456的Profile资源PUT http://~/$version/users/123456/profilesRequest Body:{    "full_name": "yanbo.ai",    "state": "Shanghai",    "title": "Senior software engineer"}

组合资源要避免资源路径嵌套

示例: 一个系统里面包含多个 applications，一个 application 又包含多个 users。那获取 user 资源的路径应该是怎样的？

看一个路径嵌套的例子：

GET http://~/$version/systems/:systemId/applications/:applicationId/users/:userId

这样做是不合理的，它会让你的接口变得越来越混乱和缺少灵活性。正确的做法是：

GET http://~/$version/systems/:systemIdGET http://~/$version/applications/:applicationId GET http://~/$version/users/:userId/

Http Methods

HTTP Operation Description
GET 获取，查找
POST 新增创建
PUT 更新
PATCH 部分更新
DELETE 删除

URL组成

  1. 网络协议(HTTP, HTTPS)
  2. 服务器地址
  3. 版本
  4. 接口名称
  5. ?参数列表
GET https://github.com/v1/trades

为什么需要版本?

当服务被更多其他系统使用的时候，服务的可用性和上下兼容变得至关重要。被外部系统依赖的服务在升级时是一个非常麻烦的事情，既要发布新的接口，又要保留旧的接口留出时间让调用者去升级。在URL中加入Version标示能很好地解决上下兼容(新老版本共存)问题。

示例1: URL中新增了Path parameter

v1版本

GET http://~/v1/trades?user_id=123456

v2版本

GET http://~/v2/:user_id/trades

示例1中的user_id参数在v2版本被加入到path parameter中，使用$version保证了v1和v2接口的共存。

示例2: 数据接口发生变化

v1版本

GET http://~/v1/accounts/yanbo.aiResponse Body:{    "user_name": "yanbo.ai",    "e_mail": "[email protected]",    "state": "Shanghai",    "title": "Senior software engineer"}

v2版本

GET http://~/v2/accounts/yanbo.aiResponse Body:{    "user_name": "yanbo.ai",    "e_mail": "[email protected]",    "profile": {        "state": "Shanghai",        "title": "Senior software engineer"    }}

示例2中的接口返回数据结构已经发生了变化。使用$version保证了v1和v2接口的共存。

URL定义限制

  1. 不使用大写字母
  2. 使用中线-代替下划线_
  3. 参数列表应该被encode过

接口分类

资源对象的CURD操作

GET http://~/$version/trades            获取trades列表GET http://~/$version/trades/:id        根据id获取单个tradePOST http://~/$version/trades           创建tradePUT http://~/$version/trades/:id        根据id更新tradePATCH http://~/$version/trades/:id      根据id部分更新tradeDELETE http://~/$version/trades/:id     根据id删除trade

服务型接口

使用services标识，根据服务的属性选择http方法。

http://~/services/$version/server-name

系统设置

使用settings标识，根据服务的属性选择http方法。

http://~/settings/$version/server-name

示例1: 搜索

GET http://~/services/$version/search?q=filter?category=file

示例2: 任务队列操作

PUT http://~/services/$version/queued/jobs          往任务队列里面添加一个新的任务DELETE http://~/services/$version/queued/jobs/:id   根据id删除任务

示例3: 更改界面语言环境

PUT http://~/settings/$version/gui/lang{    "lang": "zh-CN"}

为什么需要区分?

1.Microservices

Microservices是一个全新的概念，它主要的观点是将一个大型的服务系统分解成多个微型系统。每个微型系统都能独立工作，并且提供各种不同的服务。独立运行的特点使微型系统之间不会产生相互影响，其中的一个微型系统宕机并不会牵连到其他的微型系统。这种架构使分布式系统的节点数量大大提升。因为RESTful服务是无状态的，所以这种分解并不会带来状态共享的问题。

2.路由规则(逻辑)

当我们需要对不同属性的接口做路由规则的时候，按功能划分接口是一个很好的方案。例如：我们要对系统设置接口设置增加更严格的调用限制。

缓存

网络接口相对于堆栈接口来说数据传输极其不稳定，尽可能地减少数据传输不仅能控制这种风险还能减少流量。使用缓存还能有效地提高后台的吞吐量。

后台在响应请求时使用响应头E-Tag或Last-Modified来标记数据的版本，前台在发送请求时将数据版本通过请求头If-Match帮助后台判断缓存的使用。

Request Header

If-Match: 2390239059405940

Response Header

E-Tag: 2390239059405940Last-Modified: 2014-04-05T14:30Z

Bookmarker

在实际的环境中，有大量的查询需求是相同的。将这些搜索需求标签化能降低使用难度也可以达到重用的目的。

示例1: 查找状态为关闭的订单

普通方式

GET http://~/$version/trades?status=closed&sorting=-created_at

Bookmarker

GET http://~/$version/trades#recently_closed

或

GET http://~/$version/trades/recently_closed

HATEOAS

HATEOAS通过Web Linking的方式来描述程序的状态信息

Link 主要包含以下属性:

Property Description
rel 关联内容
href URL
type 媒体类型
method Http Method
title 标题
arguments 参数列表
value 返回值

Rel 可能为以下值:

Value Description
next 下一步
prev 上一步
first 第一步，最前
last 最后一步，最后
source 来源
self 资源自身，相对于this

Web Linking 可以通过两种方式传递至客户端:

Http Header

Link: <http://~/$version/trades?page_no=10>; rel="next", <http://~/$version/trades?page_no=19>; rel="last"

Http JSON Body

{    "links": [        {            "rel": "next",            "href": "http://~/$version/trades?page_no=1"        },        {            "rel": "last",            "href": "http://~/$version/trades?page_no=19"        }    ]}

示例1: 用户注册业务

  1. 用户填写E-Mail与密码
  2. 完善用户资料

Register Request

POST http://~/$version/accountsHeaders:    Accept: application/json    Content-Type: application/json;charset=utf-8Body:    {        "username": "[email protected]",        "e_mail": "[email protected]",        "password": "balabala"    }

Register Response

Headers:    Content-Type: application/json;charset=utf-8Status: 201 CreatedBody:    {        "uri": "http://~/$version/accounts/yanbo.ai",        "identity": "yanbo.ai",        "created_at": "2014-04-05T14:30Z",        "links": [            {                "rel": "next",                "href": "http://~/$version/accounts/yanbo.ai/profiles",                "method": "POST",                "title": "Editing Profiles",                "arguments": "status=editing"            }        ]    }

Profile Request

POST http://~/$version/accounts/yanbo.ai/profilesHeaders:    Accept: application/json    Content-Type: application/json;charset=utf-8Body:    {        "full_name": "yanbo.ai",        "state": "Shanghai",        "title": "Senior software engineer"    }

Profile Response

Headers:    Content-Type: application/json;charset=utf-8Status: 201 CreatedBody:    {        "uri": "http://~/$version/accounts/yanbo.ai/profiles",        "identity": "yanbo.ai",        "created_at": "2014-04-05T14:30Z"    }

示例2: 请看下节<分页>

HATEOAS在解决什么问题?

HATEOAS是Hypermedia as the Engine of Application State的缩写形式，中文意思为：超媒体应用状态引擎。它的核心思想是使用超媒体表达应用状态，与hypertext-driven思想是一致的。在此之前，我们大多数的程序业务控制在前台完成。例如：我们会在前台做注册流程，我们在前台判定下一步应该做什么，可以做什么。当使用HATEOAS时，这些状态流程控制都在应用程序的后台完成。我们使用超媒体来表达前台做完某一步骤之后可以做哪些? 这样一来，前台的任务就变得相当简单了，前台需要处理的是理解状态表述，数据收集和结果显示。

思考

HATEOAS会带来怎样的改变? 使用它的意义在哪?

分页

Request

GET http://~/$version/trades?page=10&pre_page=100

Response

Link Header

Link: <http://~/$version/trades?page=11&pre_page=100>; rel="next", <http://~/$version/trades?page=19&pre_page=100>; rel="last"

JSON Body

{    "links": [        {            "rel": "next",            "href": "http://~/$version/trades?page=11&pre_page=100"        },        {            "rel": "last",            "href": "http://~/$version/trades?page=19&pre_page=100"        }    ]}

安全

调用限制

为保证服务的可用性应对服务进行调用过载保护

Response Headers

X-RateLimit-Limit: 3000             调用量的最大限制X-RateLimit-Reset: 1403162176516    调用限制重置时间X-RateLimit-Remaining: 299          剩余的调用量

安全验证

RESTful服务使用Oauth2的方式进行调用授权，使用http请求头Authorization设置授权码; 必须使用User-Agent设置客户端信息, 无User-Agent请求头的请求应该被拒绝访问。

Request Header

User-Agent: Data-Server-ClientAuthorzation: Bearer 383w9JKJLJFw4ewpie2wefmjdlJLDJF

为什么建议使用Oauth2授权?

Oauth2的参与者为：客户端，资源所有者，授权服务器，资源服务器。客户端先从资源所有者得到授权码之后使用授权码从授权服务器得到token，再使用token调用资源服务器获取经过资源所有者授权使用的资源。这种授权方式的特点有：

  1. 资源所有者可以随时撤销授权许可
  2. 可以通过撤销token拒绝客户端的调用
  3. 资源服务器可以拒绝客户端的调用

通过这三种方式可以做到对资源的严格保护。资源的访问权限也把握在资源所有者的手中，而不是资源服务器。

当然，Oauth2授权框架也允许受信任的客户端直接使用token调用资源服务器获取资源。这种灵活性完全取决于客户端类型和对资源的保护程度。

为什么授权码要放在Http Header中?

  1. WEB服务器对访问做记录已经成为了行业的一个标准，访问记录不仅可以用来做访问量统计还能用来做访问特征分析。互联网广告平台就是利用访问记录来做精准营销的。如果token(授权码)包含在URL中就有很大的安全风险。
  2. 包含在URL中的token串可能被进行重定向传递。通过这两种方式入侵者可以不通过授权而使用泄漏的授权码访问那些受保护的数据，会造成数据泄漏的风险。

以Tomcat为例，访问日志为:

127.0.0.1 - - [24/Jun/2014:14:38:04 +0800] "GET /v1/accounts/yanbo.ai?token=dgdreLJLJLER798989erJKJK HTTPS/1.1" 200 343

通过对访问日志的提取，很容易得到token信息。

数据设计

交互原则

  1. 查询，过滤条件使用query string。
  2. 用来描述数据或者请求的元数据放Header中，例如 X-Result-Fields。
  3. Content body 仅仅用来传输数据。
  4. 数据要做到拿来就可用的原则，不需要“拆箱”的过程。
  5. 使用ISO-8601格式表达时间字段，例如: 2014-04-05T14:30Z。

结构

使用JSON格式传输数据，在http请求头和响应头申明Content-Type。返回的数据结构应该做到尽可能简单，不要过于包装。响应状态应该包含在响应头中！

Request

Accept: application/jsonContent-Type: application/json;charset=UTF-8

Response

Content-Type: application/json;charset=UTF-8

错误的做法

{    "status": 200,    "data": {        "trade_id": 1234,        "trade_name": "Bala bala"    }}

正确的做法

Response Headers:    Status: 200Response Body:    {        "trade_id": 1234,        "trade_name": "Bala bala"    }

示例1: 创建User对象

POST http://~/$version/usersRequest    headers:        Accept: application/json        Content-Type: application/json;charset=UTF-8    body:        {            "user_name": "Andy Ai"        }Response    status: 201 Created    headers:        Content-Type: application/json;charset=UTF-8    body:        {            "uri": "http://~/$version/users/1234",            "identity": 1234,            "created_at": "2014-04-05T14:30Z",            "links": [                {                    "rel": "next",                    "href": "http://~/gui/users/1234"                }            ]        }

为什么是JSON?

JSON 是一种可以跨平台高扩展的轻量级的数据交换格式。易于人阅读和编写，同时也易于机器解析和生成。

属性定义限制

  1. 不能使用大写(大小写友好)
  2. 使用下划线_命名(连接两个单词)
  3. 属性和字符串值必须使用双引号””

提取部分字段

无状态服务器应该允许客户端对数据按需提取。在请求头使用X-Result-Fields指定数据返回的字段集合。

例如：trade 有trade_id, trade_name, created_at 三个属性，客户端只需其中的trade_id与trade_name属性。

Request Header

X-Result-Fields: trade_id,trade_name

子对象描述

数据里面的子对象使用URI描述不应该被提取，除非用户指定需要提取子对象

示例: trade里面的order对象

错误的做法

{    "trade_id": "123456789",    "full_path": null,    "order": {        "order_id": "987654321"    }}

正确的做法

{    "trade_id": "123456789",    "order": "http://~/$version/orders/987654321"}

应用指定提取子对象，需要在请求头声明X-Expansion-Fields

Request

X-Expansion-Fields: true

为什么要客户端指定提取子对象时才提取?

懒模式服务能够最大程度地节省运算资源。虽然与客户端交互的次数有所增加，但是能做到按需提取，按需响应，这也是响应式设计的一大特点。客户端的用户行为模式无法真实地模拟，也就无法确定哪些资源需要做到一次性推送，让客户端按需使用是一个不错的方式。

关于空字段

应该在返回结果里面剔除空字段，因为null值传输到客户端并没有实际的含义，反而增加了占用空间。

Tips

使用HTTP Header时，优先使用合适的标准头属性。用X-作为前缀自定义一个头属性，例如: X-Result-Fields。

状态码&错误处理

应用状态码

Code HTTP Operation Body Contents Description
200 GET,PUT 资源 操作成功
201 POST 资源,元数据 对象创建成功
202 POST,PUT,DELETE,PATCH N/A 请求已经被接受
204 DELETE,PUT,PATCH N/A 操作已经执行成功，但是没有返回数据
301 GET link 资源已被移除
303 GET link 重定向
304 GET N/A 资源没有被修改
400 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 参数列表错误(缺少，格式不匹配)
401 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 未授权
403 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 访问受限，授权过期
404 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 资源，服务未找到
405 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 不允许的http方法
409 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 资源冲突，或者资源被锁定
415 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 不支持的数据(媒体)类型
429 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 请求过多被限制
500 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 系统内部错误
501 GET,PSOT,PUT,DELETE,PATCH 错误提示(消息) 接口未实现

容器状态码

容器状态码是指http容器的状态码，应用不应该使用或限制使用

Code HTTP Operation Body Contents Description
303 GET link 静态资源被移除,应用限制使用
503 GET,PSOT,PUT,DELETE,PATCH text body 服务器宕机

Tips

4开头的错误用来表达来自于客户端的错误，例如: 未授权，参数缺失。5开头的错误用来表达服务端的错误，例如: 在连接外部系统(DB)发生的IO错误。

错误信息格式

错误信息应该包含下列内容:

  1. 错误标题 message, 必须
  2. 错误代码 error code, 必须
  3. 错误信息 error message, 必须
  4. 资源 resource, 可选
  5. 属性 field, 可选
  6. 文档地址 document, 可选

Tips

Error Code 尽可能做到简洁明了，提取异常的关键字并且使用下划线_把它们连接起来。

示例: 调用频率超过限制，Response:

Headers:    Content-Type: application/json;charset=UTF-8    X-RateLimit-Limit: 3000    X-RateLimit-Reset: 1403162176516    X-RateLimit-Remaining: 0{    "message": "Message title",    "errors": [        {            "code": "rate_limit_exceeded",            "message": "Too Many Requests. API rate limit exceeded",            "document": "https://developer.github.com/v3/gists/"        }    ]}

锦上添花

  1. 格式化(Pettyprint)JSON数据(返回结果)并且使用gzip压缩，Pettyprint易于阅读，多余的空格在经过gzip压缩之后占用空间比压缩之前更小。
  2. 重写Server头
  3. 返回X-Powered-By

Response Headers

X-Pretty-Print: trueContent-Encoding: gzipServer: [email protected]X-Powered-By: yanbo.ai;[email protected]

附页

框架&工具

参考资料

时间： 2024-10-26 16:36:58

RESTful最佳实践的相关文章

RESTful 最佳实践

除了传统对于远程调用的需求,近来移动开发对于api的规范化需要,restful作为一个流行的接口调用方式,值得深入了解. 声明 本文属于转载:原文 此文为实践总结,是自己在实践过程中积累的经验和"哲学".部分内容参考相关资料,参考内容请看尾页.建议对RESTful有一定了解者阅读! "哲学" 不要为了RESTful而RESTful 在能表达清楚的情况下,简单就是美 接口路径设计 接口设计原则 URI指向的是唯一的资源对象示例: 指向ID为cloud.mario的Ac

三分钟彻底了解Restful最佳实践

REST是英文representational state transfer(表象性状态转变)或者表述性状态转移;Rest是web服务的一种架构风格;使用HTTP,URI,XML,JSON,HTML等广泛流行的标准和协议;轻量级,跨平台,跨语言的架构设计;它是一种设计风格,不是一种标准,是一种思想 Rest架构的主要原则 网络上的所有事物都被抽象为资源 每个资源都有一个唯一的资源标识符 同一个资源具有多种表现形式(xml,json等) 对资源的各种操作不会改变资源标识符 所有的操作都是无状态的

RESTful API 设计最佳实践（转）

摘要:目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API格式如何?你的API是否应该加入版本信息? 背景 目前互联网上充斥着大量的关于RESTful API(为了方便,以后API和RESTful API 一个意思)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API格式如何?你的API是否应该加入版本信息?当你开始写一个app的时候,特别是后端模型部分已经写完

RESTful API 设计最佳实践

1. 背景 REST(英文:Representational State Transfer,表述性状态转移)描述了一个架构样式的网络系统,比如 web 应用程序. 目前互联网上充斥着大量的关于RESTful API(为方便,下文中"RESTful API "简写为"API")如何设计的文章,然而却没有一个"万能"的设计标准:如何鉴权?API 格式如何?你的API是否应该加入版本信息?当你开始写一个app的时候,特别是后端模型部分已经写完的时候,你

[转]10个有关RESTful API良好设计的最佳实践

Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GET, DELETE, POST 和 PUT来操作资源. 下面是进行RESTful Web API十个最佳实践,能为你提供一个良好的API设计风格. 1.使用名词而不是动词 Resource资源 GET读 POST创建 PUT修改 DELETE /cars 返回 cars集合 创建新的资源 批量更新c

10个有关RESTful API良好设计的最佳实践

Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的. 通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GET, DELETE, POST 和 PUT来操作资源. 下面是进行RESTful Web API十个最佳实践,能为你提供一个良好的API设计风格. 1.使用名词而不是动词 Resource资源 GET读 POST创建 PUT修改 PATCH部分修改 DELETE /cars 返回 cars集合 创建

RESTful API的十个最佳实践

WebAPI在过去几年里非常的盛行,我们很多以往的技术手段都慢慢的转换为使用WebAPI来开发,因为它的语法简单规范化,以及轻量级等特点,这种方式收到了广泛的推崇. 通常我们使用RESTFul(Representational State Transfer)的设计方式来设计Web api,这通常用来分离API结构了业务逻辑,它使用典型的HTTP方法,诸如GET,POST.DELETE,PUT来和资源进行交互. 以下是设计RESTful API的是个最佳实践: 1. 使用名词而不是动词 为了易于理

RESTful API 设计最佳实践(转)

背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中“RESTful API ”简写为“API”)如何设计的文章,然而却没有一个”万能“的设计标准:如何鉴权?API 格式如何?你的API是否应该加入版本信息?当你开始写一个app的时候,特别是后端模型部分已经写完的时候,你不得不殚精竭虑的设计和实现自己app的public API部分.因为一旦发布,对外发布的API将会很难改变. 在给SupportedFu设计API的时候,我试图以实用的角度来解决上面提到的问题.我希望可以设计

我们必须要知道的RESTful服务最佳实践

看过很多RESTful相关的文章总结,参齐不齐,结合工作中的使用,非常有必要归纳一下关于RESTful架构方式了,RESTful只是一种架构方式的约束,给出一种约定的标准,完全严格遵守RESTful标准并不是很多,也没有必要.但是在实际运用中,有RESTful标准可以参考,是十分有必要的. 实际上在工作中对api接口规范.命名规则.返回值.授权验证等进行一定的约束,一般的项目api只要易测试.足够安全.风格一致可读性强.没有歧义调用方便我觉得已经足够了,接口是给开发人员看的,也不是给普通用户去调