Published on

REST API DESIGN

Authors

REST 缩写: REpresentation State Transfer
最初想法有Roy Fielding 在他的博士论文 Architectural Styles and the Design of Network-based Software Architectures 中提出来。

REST 有6大必要条件

  • Uniform Interface 统一接口
    统一接口定义了客户端和服务器之间的接口。简化并解耦了架构，使得双方都可以独立进化。

    • Resource-based 基于资源
      URI as resource identifiers

    • Manipulation of Resources Through Representations

    • Self Descriptive Messages

    • Hypermedia as the engine of Application State

  • Stateless 无状态
    服务器端处理请求需要的状态都包含在客户端发送的请求当中。状态可能是URI的一部分，查询字符串参数，body，也可能在Header中。URI 唯一标识资源，body 包含了资源的状态。无状态使得架构更具扩展性

  • Cacheable 可缓存

  • Client-Server 客户端-服务器模型

  • Layered System 分层设计的系统

  • Code on Demand (optional) 按需编码
    Java Applets or javascript

REST enables:
performance, scalability, simplicity, modifiability, visibility, portability and reliability.

HTTP 状态码

Tips

  • 使用HTTP 动词

    • GET: 读取某个特定资源或者资源集合

    • PUT: 更新某个资源

    • POST: 创建新的资源。如果找不到合适的动词就用这个动词

    • DELETE: 删除某个资源

Provide Sensible Resource Names

设计一个好的API 80% 的艺术 + 20% 的科学

  • URL中使用标识，而不是查询字符串，如 /users/12345

  • 巧妙使用URL 的等级结构特性来标识资源的结构

  • 为客户端设计，而不是为数据设计

  • 资源名称使用名词，使用HTTP 的方法来表示请求的动作部分

  • URL 中使用复数名词

  • 避免使用集合词

  • URL 使用小写，使用 '_' 或者 '-' 来分割单词

  • 尽量保持URL 短小

Use HTTP Response Codes to Indicate Status

Offer Both JSON and XML

Create Fine-Grained Resources

Consider Connectedness

Idempotence

幂等性

Reference:

Discuss on Twitter • View on GitHub