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

Restful API Specification draft 1

  • 722
Loading comments...

More from Andy Song