RestFUL API SPECIFICATION

(HunterOn）

PROTOCOL SUPPORT

(支持协议）
  • HTTP(S) 1.1 （2.0  optional)
    • Support external requests (支持网页，移动设备以及其他外部系统的请求）
    • Fundmental prototype for platform (可以作为基础的平台化的原型）
  • RPC 
    • Support internal requests (支持内部系统之间的请求）
  • WebSocket 
    • Support pulling mode or scheduled requests (支持拉结构的以及定时的请求）

MESSAGES FORMAT

（消息格式）
  • JSON  ---- What we choose
    • Benefit: text format, easy reading, javascript friendly natually ---- 文本形式，易读,  javascript 友好性
    • Weakness:  wasting space, insecurity awareness ---- 浪费空间，安全性不高
  • BSON ---- Compressed JSON
    • Benefit: stream format, space saving ---- 流格式，节省空间
    • Weakness: difficult to reading, javascript plugin need --- 难于阅读，javascript需要插件支持。

Architecture style

（架构风格）

  1. First version, IMPERATIVE MODE  - 第一版，是以传统的命令的交互模式进行



2.  Second version, FUNCTIONAL(REACTOR) MODE - 第二版，是以函数式以及反应器模式

SOME KEY ARCHITECTURE ATTRIBUTES 1

（一些关键架构的属性）
  • Scalability  ---- 扩展性
    • Domain  Model, Little Granularity --- 领域模型，细粒度  
  • Availability ---- 可使用性
    • Deploy per Domain  ---- 可以做到不同领域单独发布
  • Idempotence  ----  冥等性
    • Partial support  ---- 部分支持，需要一些人为的干预
  • Consistency  ---- 一致性
    • Need consider TX  --- 事物方面需要一些策略以及设计

Some KEY ARCHITECTURE ATTRIBUTES 2

（一些关键架构的属性）
  • Security ----安全
    • MD5 hashing token
    • Authentication and Authorization
    • OAUTH 2.0

  • Latency----延迟
    • GZIP turn on
    • Unformatted JSON mode

  • Tracing----侦测
    • EventId ---- session id, timestamp, etc.
    • Caller 

  • Compatibility----兼容性
    • Versioning 

KEY ReStFUL API PATTERN [HTTP(s)]


  • CREATE ----  创建
    • HTTP(S)  ---- POST

  • UPDATE ---- 更新
    • HTTP(S) ---- PUT （也可以POST)

  • DETELE ---- 删除
    • PHYSICAL：HTTP(S) ---- DETELE
    • LOGICAL：HTTP(S)----PUT

  • GETTER ---- 获取一个多个对象
    • HTTP(S) ---- GET

  • AdHoc SEARCH ---- 搜索
    • HTTP(S) ---- GET

  • State flow or Async-invocation----- 状态流或者异步调用
    • HTTP(S) ---- POST

EVERY Request of API SHOULD INCLUDE

（每个Restful的api请求应该包含）
  • Mandatory （必须）
    • Version  ---- 版本信息
    • Domain Model (Entity) ---- 操作的业务对象
    • EventID ---- 事件ID，方便随后Tracing的工作
      • Hashing of SessionID，UserID，Page，Action，TxID
    • Token ---- 验证合法的调用
    • CheckSum ---- 验证接受信息的合法性
    • TimeStamp ---- 时间
  • Optional （可选）
    • Qos ---- 调用频率，以及超时的设置

EVERY RESPONSE OF API SHOULD INCLUDE
（每个Restful的api回复应该包含）

  • Mandatory （必须）
    • CheckSum --- 返回内容的CheckSum
    • EventID ---- 相关的时间ID
    • TimeStamp ---- 返回时间
    • Sucess or Failure ---- 成功或者失败以及相关的详细信息
  • Optional （可选）
    • Profiling ---- 该次API的使用时间
    • Qos ----- 返回对应的Qos

HTTP(S) RESTFUL API URL PATTERN

(API URL 的模式)

http(s)://api.hunteron.com/services/<version>/<domain>

RESTUFL API Request SKeTch

（API 请求骨架）
  • JSON  body
{
head: {... ...} /*Mandatory*/,
param:{... ...}/*Optional*/,
misc:{... ...}/*Optional*/
}

RESTFUL API RESPONSE SKETCH

（API 返回骨架）
{
head: {... ...} /*Mandatory*/,
result:{... ...}/*Optional*/,
misc:{... ...}/*Optional*/
}

Continuing updating TBD

（持续更新中）

Restful API Specification draft 1

By Andy Song

Made with Slides.com

Restful API Specification draft 1

  • 945

More from Andy Song