RESTful Best Practices

RESTful Best Practices

tags: RESTful Specification Apis Designjavascript

Author: Andy Ai
Weibo: NinetyHhtml

声明

此文为实践总结,是本身在实践过程当中积累的经验和"哲学"。部份内容参考相关资料,参考内容请看尾页。建议对RESTful有必定了解者阅读!java

哲学

  • 不要为了RESTful而RESTfulgit

  • 在能表达清楚的状况下,简单就是美github

接口路径设计

接口设计原则

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

示例: 指向ID为yanbo.aiAccount对象json

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

URI能够隐式指向惟一的集合列表

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

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

聚合资源必须经过父级资源操做

示例: ProfileUser的聚合资源,User有一个惟一且私有的Profile资源,只能经过User操做Profile缓存

更新user_id为123456的Profile资源
PUT http://~/$version/users/123456/profiles

Request 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/:systemId
GET 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保证了v1v2接口的共存。

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

v1版本

GET http://~/v1/accounts/yanbo.ai
Response Body:
{
    "user_name": "yanbo.ai",
    "e_mail": "yanbo.ai@gmail.com",
    "state": "Shanghai",
    "title": "Senior software engineer"
}

v2版本

GET http://~/v2/accounts/yanbo.ai
Response Body:
{
    "user_name": "yanbo.ai",
    "e_mail": "yanbo.ai@gmail.com",
    "profile": {
        "state": "Shanghai",
        "title": "Senior software engineer"
    }
}

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

URL定义限制

  1. 不使用大写字母

  2. 使用中线-代替下划线_

  3. 参数列表应该被encode过

接口分类

资源对象的CURD操做

GET http://~/$version/trades            获取trades列表
GET http://~/$version/trades/:id        根据id获取单个trade
POST http://~/$version/trades           建立trade
PUT http://~/$version/trades/:id        根据id更新trade
PATCH http://~/$version/trades/:id      根据id部分更新trade
DELETE 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`是一个全新的概念,它主要的观点是将一个大型的服务系统分解成多个微型系统。每一个微型系统都能独立工做,而且提供各类不一样的服务。独立运行的特色使微型系统之间不会产生相互影响,其中的一个微型系统宕机并不会牵连到其余的微型系统。这种架构使[分布式系统的节点数量][6]大大提高。由于RESTful服务是无状态的,因此这种分解并不会带来状态共享的问题。
  2. 路由规则(逻辑)

    当咱们须要对不一样属性的接口作路由规则的时候,按功能划分接口是一个很好的方案。例如:咱们要对系统设置接口设置增长更严格的调用限制。

缓存

网络接口相对于堆栈接口来讲数据传输极其不稳定,尽量地减小数据传输不只能控制这种风险还能减小流量。使用缓存还能有效地提升后台的吞吐量。
后台在响应请求时使用响应头E-TagLast-Modified来标记数据的版本,前台在发送请求时将数据版本经过请求头If-None-Match帮助后台判断缓存的使用。

Request Header

If-None-Match: 2390239059405940

Response Header

E-Tag: 2390239059405940
Last-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/accounts
Headers:
    Accept: application/json
    Content-Type: application/json;charset=utf-8
Body:
    {
        "username": "yanbo.ai@gmail.com",
        "e_mail": "yanbo.ai@gmail.com",
        "password": "balabala"
    }

Register Response

Headers:
    Content-Type: application/json;charset=utf-8
Status: 201 Created
Body:
    {
        "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/profiles
Headers:
    Accept: application/json
    Content-Type: application/json;charset=utf-8
Body:
    {
        "full_name": "yanbo.ai",
        "state": "Shanghai",
        "title": "Senior software engineer"
    }

Profile Response

Headers:
    Content-Type: application/json;charset=utf-8
Status: 201 Created
Body:
    {
        "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-Client
Authorzation: 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/json
Content-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: 200
Response Body:
    {
        "trade_id": 1234,
        "trade_name": "Bala bala"
    }

示例1: 建立User对象

POST http://~/$version/users

Request
    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_idtrade_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
102 Processing GET, POST, PUT, DELETE, PATCH 处理状态的信息 当前请求正在处理
200 Ok GET, PUT 资源 操做成功
201 Created POST, PUT 资源, 元数据 对象建立成功
202 Accepted POST, PUT, DELETE, PATCH 处理信息 请求已经被接受
204 No Content DELETE, PUT, PATCH N/A 操做已经执行成功,可是没有返回数据
301 Moved Permanently GET link 资源已被移除
303 See Other GET link 重定向
304 Not Modified GET N/A 资源没有被修改
400 Bad Request GET, POST, PUT, DELETE, PATCH 错误提示 参数列表错误(缺乏,格式不匹配)
401 Unauthorized GET, POST, PUT, DELETE, PATCH 错误提示 未受权
403 Forbidden GET, POST, PUT, DELETE, PATCH 错误提示 访问受限,受权过时
404 Not Found GET, POST, PUT, DELETE, PATCH 错误提示 资源,服务未找到
405 Method Not Allowed GET, POST, PUT, DELETE, PATCH 错误提示 不容许的http方法
406 Not Acceptable GET, POST, PUT, DELETE, PATCH 错误提示 媒体内容不符合要求
408 Request Timeout GET, POST, PUT, DELETE, PATCH 错误提示 请求超时
409 Conflict GET, POST, PUT 错误提示 资源冲突,重复的资源
415 Unsupported Media Type GET, POST, PUT, DELETE, PATCH 错误提示 不支持的数据(媒体)类型
422 Unprocessable Entity GET, POST, PUT, PATCH 错误提示 请求格式正确,可是因为含有语义错误,没法响应。
423 Locked GET, POST, PUT, DELETE, PATCH 错误提示 当前资源被锁定
429 Too Many Requests GET, POST, PUT, DELETE, PATCH 错误提示 请求过多被限制
500 Internal Server Error GET, POST, PUT, DELETE, PATCH 错误提示 系统内部错误
501 Not Implemented GET, POST, PUT, DELETE, PATCH 错误提示 接口未实现

容器状态码

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

Code HTTP Operation Body Contents Description
303 GET link 静态资源被移除,应用限制使用
503 GET, POST, 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: true
Content-Encoding: gzip
Server: ods@shuyun.com
X-Powered-By: yanbo.ai;email=yanbo.ai@gmail.com

附页

框架&工具

参考资料

未经赞成不可转载, 转载需保留原文连接与做者署名。

相关文章
相关标签/搜索