適切なAPIを設計するために注意したいこと「インタフェース」

アプリ、Webサービスと数多くのインターネットを使ったサービスが登場するのに比例してWeb APIも次々と作られています。Web APIのマーケットが拡がっていくことで認知が高まり、さらにWeb APIが開発されていくという好循環が生まれています。

その一方で乱立することによって、Web APIの品質が問題になってきます。Web APIではWebブラウザを使ったアクセスとは異なり、基本的にプログラムからのアクセスを考えなければなりません。そのため不用意なセキュリティホールがあったりすると、あっという間に大きな問題（データの消失であったり、乗っ取りであったり）が発生する可能性を秘めています。

そこで私たちはWeb APIの設計に際して標準規則を策定しています。その規則に沿ってWeb APIの開発を進めることで、可用性はもちろん堅牢性や安全性を意識した情報の提供ができるようになります。今回はその項目の一つである インタフェース について一部を紹介します。

REST APIであること

昨今のWeb APIの流れはREST APIにあります。つまりURLでデータ（リソース）を特定し、HTTPメソッド（GET/POST/PUT/DELETE）によってそのデータに対して行う操作を特定します。技術的に言うと、

に対応させるということです。詳しくはREST - Wikipediaをご覧ください。

プロトコル

これから作られるWeb APIについてはHTTP 1.1になっているべきでしょう。HTTP 1.1についてはKeep-AliveとHOSTヘッダの特徴が挙げられますが、一般的なHTTPサーバであるApacheやnginxなどを利用している限りは特に意識することはないかと思います。Web APIを提供する上ではあえて独自のプロトコルを定義するようなことは避け、標準技術に沿って進めるのが良いでしょう。

Content-Type

Web APIはデータを返却する際に適切なContent-Typeを設定しておく必要があります。今のトレンドとしては、XMLとJSONがあるかと思います。

XML

XMLで使われるContent-Typeは以下の5つがあります。これはRFC 3023で定義されています。

• text/xml
• application/xml
• text/xml-external-parsed-entity
• application/xml-external-parsed-entity
• application/xml-dtd

Web APIとして用いる上では application/xml がお勧めです。

JSON

JSONで使われるContent-Typeは application/json のみ定義されています。これは RFC 4627 に記載されています。なのでJSONデータを返却する際には application/json を Content-Type として指定しましょう。

適切なWeb APIを設計すると、リリース後の更新において設計が破綻することがなかったり、拡張性も担保されるようになります。もちろん、設計が統一されることで不用意なセキュリティホールが出るのを防ぐこともできるでしょう。

エンタープライズにおけるWeb API開発および利用や評価において参考にしてください。