· JSON Schema Plant UML Web API

WEB+DB PRESS Vol.82 の「Web APIデザインの鉄則」特集を読んだ。

  • このエントリーをはてなブックマークに追加

WEB+DB PRESS Vol.82

WEB+DB PRESS Vol.82を買いました。Go言語が載ってるからという理由で買いましたが、「Web APIデザインの鉄則」という特集があって、おもしろそうなのでよんでみました。

第1章 Web APIの基礎知識

この特集ではメッセージ形式をJSONとするRESTful APIの設計について書かれていますが、REST以外のスタイルにRPCなどもあるのに、なぜRESTful APIにするのかを、基礎から丁寧に書いてくれています。

ちなみに、RESTfulなWeb APIをここでは、ROA(Resource Oriented Architecture)に沿って設計することと定義しています。

第2章 リソース設計

「Eメール送信を行うためのAPI」を題材としています。その題材を元に、リソースに含まれるフィールドをどのように定義するか、その定義をどうやって明文化するかが書かれています。おすすめは、JSON Schemaという手法を用いることだとそうです。JSON Schemaを使いながら、題材に必要なリソースを定義していっています。

語彙を決めるのには先人の知恵([schema.org][1]や OpenSeacrh) などを参考にするとよいとのことです。

第3章 インターフェース設計

ここでは、エンドポイントURI・HTTPメソッド・クエリパラメータを定めていきます。第2章で作成したJSON Shemaによる定義に追加していきます。

「新しいリソースを作成するエンドポイント」や「すでに存在するリソースを削除するエンドポイント」のそれぞれに対して、どのような要件で作成するかが解説されています。「HTTPメソッドの選び方」も詳しく書いてあります。

第4章 エラー表現とドキュメント

「エラーがなぜ起こったのか」「どのようにすればそれを解決できるか」を機械がわかるような仕組みにするために、エラー表現をどのように決めていくかについて説明されています。

また、文書だけでは説明できない部分は図を書いたりしますが、その図を作成するPlant UMLというツールを紹介しています。

感想

Web APIの設計について非常に勉強になりました。知らないツールなどもあったので、積極的につかっていきたいと思う。

WEB+DB PRESS Vol.82

WEB+DB PRESS Vol.82

  <div class="amazlet-powered-date" style="font-size:80%;margin-top:5px;line-height:120%">
    posted with <a href="http://www.amazlet.com/" title="amazlet" target="_blank">amazlet</a> at 14.09.11
  </div>
</div>

<div class="amazlet-detail">
  山口 徹 Jxck 佐々木 大輔 横路 隆 加来 純一 山本 伶 大平 武志 米川 健一 坂本 登史文 若原 祥正 和久田 龍 平栗 遵宜 伊藤 直也 佐藤 太一 高橋 俊幸 海野 弘成 五嶋 壮晃 佐藤 歩 吉村 総一郎 橋本 翔 舘野 祐一 中島 聡 渡邊 恵太 はまちや2 竹原 河合 宜文 <br />技術評論社 <br />売り上げランキング: 663
</div>

<div class="amazlet-sub-info" style="float: left;">
  <div class="amazlet-link" style="margin-top: 5px">
    <a href="http://www.amazon.co.jp/exec/obidos/ASIN/4774166278/kwmt27-22/ref=nosim/" name="amazletlink" target="_blank">Amazon.co.jpで詳細を見る</a>
  </div>
</div>

[1]: http://schema.org/Person

  • このエントリーをはてなブックマークに追加
  • LinkedIn
  • Tumblr
  • Reddit
  • Google+
  • Pinterest
  • Pocket