読者です 読者をやめる 読者になる 読者になる

KZKY memo

自分用メモ.

REST API まとめ

REST API設計に関してまとめようと思ったけれど,
既に誰かがやっていたのでまとめofまとめになってしまうため,簡単なメモとして残す.

素晴らしいまとめ.

REST APIとは

REST APIとはときかれれて,一文で答えるならば,
「EntityやResourceに対してCRUD操作をするAPIです.」

もう少し冗長にいう場合,
「HTTPのPOST, GET, PUT, DELETE メソッドを,EntityやResourceに対してのCRUD操作, Create, Read, Update, Deleteに対応づけたWebAPIです.」

と,RPC over HTTPしか知らない人に説明する.

超基本的設計

URLの設計

Entity1つの場合
/${pathto}/api/v${number}/${entities}/${id}?${k0}=${v0}&${k1}=${v1}

とか

Entity間に親子関係とかがある場合
/${pathto}/api/v${number}/${entities0}/${id0}/${entities1}/${id1}

変数

  • pathto: apiへのパス
  • v${number}: version
  • ${entities}: entityの複数
  • ${id}: entityのidとか名前,e.g., entities=artists, id=kzky. ${id}ないとentity一覧を返す場合が多い.
  • ${k0}, ${v0}: GETするときのパラメータで細かい条件をつける. e.g., limits=30.

Over HTTPなので名前をあまり冗長にしないほうがいい.特にGETパラメータを省略系にして,GETパラメータ以外はちゃんと書くようにする.

素晴らしいサンプル

Google Play Store

例えばこのサンプル
https://play.google.com/store/apps/details?id=com.google.android.apps.currents

上記の超基本設計にむりやり対応させるならば,

  • pathto = store
  • entities=apps
  • id=details?id=xxx

idの部分をdetailsとして,app(=entity)に関する情報はdetailsのGETパラメータに含めるようにしている.この例だとidがpkgnameみたいな感じ.

Cloudera Manager

http://cloudera.github.io/cm_api/apidocs/v9/index.html

このURL自体というより,このURLに飛ぶとCloudera Managerが提供しているREST API一覧が登場する.

Hadoopが提供するService, 及びそのコンポーネントをうまく整理し,統治しているCloudera様だからできていることだと思う.

最後に

WebAPI設計といってもRESTスタイルにこだわらなくてもいい.
Entityに対するCRUD操作という考え方が人間にわかりやすいから採用されやすいだけ.