適切なAPIを設計するために注意したいこと「データフォーマット」

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

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

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

データフォーマットはXMLまたはJSON

現在、Web APIで送受信されるフォーマットはXMLまたはJSONがデファクトスタンダードになっています。特に一般開発者向けに公開されるものはWebブラウザからも扱いやすいJSONが増えています。Webサービスをはじめ、エンタープライズ間でやり取りされるデータについてはXMLを使うことも多いです。

データのやり取りに際して旧来の手法であるCSVについては現在は非推奨とすべきです。項目の順番や長さによるデータ定義や改行やエスケープすべき文字が入った時の処理など、扱いの柔軟性が問題になります。

Web APIにおけるフォーマットの指定

Web APIが返す出力についてはリクエスト時にフォーマットが指定できるようになっているべきです。例えばURIで指定する場合は次のようになるでしょう。

http://example.com/〜.json # JSONリクエストの場合

または format パラメータに jsonまたはxmlなどと文字で指定する場合もあります。formatパラメータの場合、jsonp（JSON with padding）を指定することも考えられます。URL指定の場合はcallbackパラメータのあるなしでJSON/JSONPと出力を変えることが多いように見えます。

http://example.com/〜?format=json

いずれの場合においても利用者が使いたいと思うフォーマットを動的に指定できるのが望ましいと考えています。

スキーマの提供

XML、JSONのいずれにおいても実装とAPI仕様の乖離を避けるためにスキーマを提供すべきです。XML Schemaは昔からよく知られていますし、JSONにおいてもJSON Schemaが定義されています。

パラメータ命名規則について

パラメータ名は分かりやすいものをつけるのは当然ですが、大文字小文字についても注意が必要です。私たちはLCC（Lower Camel Case）を推奨しています。例えばユーザ名であればuserNameといった形で先頭を小文字に、その後の単語は頭を大文字にしています。その他の手法としては_（アンダースコア）を使う場合もあるかと思います。

文字エンコード

文字エンコードはUTF-8であるべきです。日本語をはじめ、複数バイト文字圏ではエンコーディングが最大の問題、かつ不具合の原因になりますので、UTF-8を使っておくのが安全であり、基本になるでしょう。

Web APIは人ではなくシステムを対象にして開発されています。そのため内部の実装がブラックボックスになり、Web APIおよびそのドキュメントがそのまま仕様として外部に公開されることになります。適切なWeb API設計を行うことがシステムの可用性、柔軟性、堅牢性につながることでしょう。

ぜひ皆さんのWeb API設計において参考にしてください。