はじめに
Web APIについての理解が浅かったので学んだことをまとめたいと思います。
Web APIとAPIの違い
これら二つは同義で使われることがほとんどですが、厳密には違いがあるようです。
APIとは
-
Application Programming Interfaceの略称であり、何かしらのサービス提供者が、そのサービス利用するために提供するインターフェース。 - APIを利用すれば、同じ機能を持ったサービスを開発する必要がないため、開発効率の向上や開発費用の低減が期待できる。
- API利用者が用いるプログラミング言語と同じ言語で提供されることが多い。
Web APIとは
- API提供者とAPI利用者とのやりとりを
HTTP／HTTPSベースで実現するAPI。 - 異なるプログラミング言語で開発されたアプリケーション間を連携させることが可能。
このように細かい違いがあります。次に、Web APIについてもう少し掘り下げてみたいと思います。
Web APIとは何か
Web APIとはHTTPプロトコルを利用してネットワーク越しに呼び出すAPIのことです。ソフトウェアコンポーネントの外部インターフェース、つまり機能はわかってるけども中身の実際の動作は詳しくわからない機能のカタマリを、外部から呼び出すための仕様のことを指します。
プロトコルとしてHTTPを使うため、そのエンドポイントはURIによって指定されます。
URIにアクセスすることで、サーバー側の情報を書き換えたり、サーバー側に置かれた情報を取得できたりすることができるウェブシステムで、プログラムからアクセスしてそのデータを機械的に利用するためのものです。
機械的にというのは、ブラウザを使って人間が直接アクセスすることを目的としたURIではないという意味です。実際にAPIを使ってデータを取得してみると、ウェブページを表示する際のHTMLではなく、JSONという形式として取得できます。これは、APIが直接人間がブラウザに入力したり、リンクをクリックしたりしてアクセスするものではなく、そのデータはプログラムが取得して他の目的に使うものであるということを示しています。
HTMLは最終的に人間がブラウザ上で読むことを前提とした情報が埋め込まれているのに対し、APIが返すデータはもっとデータを直接活用するための形式になっており、加工するなど様々な目的で利用可能という違いがあります。
URIにアクセスするとXMLやJSONなどのデータが返ってくるシンプルなAPIは、XML over HTTPやJSON over HTTPと呼ばれています。ちなみにこうしたAPIをREST APIと呼ぶ場合もあります。
Web APIの重要性
Web APIを公開するのとしないのとでは、その企業やサービスの価値を左右してしまうケースもあります。例えば、Amazonが公開しているAPIにはアフェリエイトと結び付けられており、このAPIを使うことで誰でも簡単にAmazonの商品を自分のサイトから販売して収益の一部を得ることができます。これによりAmazonは収益を大きく押し上げることに成功しました。
他の例としては、よく登録やログイン画面でGoogle、Facebook、Twitterでログインする機能を見たことがあると思います。これもAPIがなせる技です。
このようにAPIを公開することにより、他の人たちがそのサービスに付加価値を与えてくれて、自分たちの開発したサービスが発展する力をもらうことができます。
昨今のウェブアプリケーション
今まではウェブアプリケーションの切り替えはページ遷移をともなって行われていました。しかし、最近ではページ遷移をせずに情報を取得し、機能を提供することが当たり前となっています。これによってデータサイズを小さくできたり、データのやり取りのタイミングを調節することでユーザー体験が向上します。
そしてHTML1ページで構成されるSPAというものもあります。従来のWebページでは遷移時にページ全体が書き換わりますが、SPAでは JavaScript を用いてページ内の HTML の一部を差し替えてコンテンツを切り替えています。 これにより、ブラウザの挙動に縛られないUIの実現や、パフォーマンスの向上が可能になります。
こうしたスタイルのWebサービスを構築しようとした場合は、必然的にAPIを設計する必要が出てきます。
エンドポイントの設計
APIの利用者は、エンドポイントにアクセスすることでAPIの機能を利用することができます。APIのエンドポイントはURIなので、通常のウェブサイトやサービスと同様にURIの設計というものが重要になってきます。
URIを設計するにあたり、非常に重要な原則があります。
覚えやすく、どんな機能を持つURIなのかが一目でわかる！
わかりやすい設計をすることで、APIを利用する開発者がエンドポイントを間違ったり、利用方法を間違ったりする確率を下げることができます。設計を疎かにしてしまうと、APIの評価を下げてしまったり間違ったアクセスが大量に行われて、APIを配信するサーバーに負荷がかかってしまうという問題が発生する可能性があります。
適切にURIを設計するためには以下のことを意識する必要があります。
人間が読んで理解できるURI
人間が読んで理解できるURIとは、そのURIを見ればそれ以外の情報がなくてもそれが何を目的としたものなのかがある程度わかることを意味します。
例えば以下のような意味不明なURIがあったとします。
http://api.example.com/au/x/
apiと入っているのでAPIなのはわかりますが、auもxも意味が全くわかりませんし推測することができません。このようなわかりずらいURIを設計しないためにも次のことを意識する必要があります。
- なるべく省略形は使わない
- 英単語を使用する
- 適切な単語を使い、スペルミスをしない
短く入力しやすいURI
短くて入力しやすいということは、覚えやすいということにも繋がります。長いURIは不要な情報が入っていたり、重複してしまったりしています。例として以下のエンドポイントがあったとします。
http://api.example.com/user/api/search
apiやsearchが入っていることから、検索用のAPIということはわかりますがapiがホストとパスで重複してしまっています。そこで、パスのapiをなくすことで、短くシンプルなURIにすることができます。
大文字小文字が混在していないURI
大文字小文字が混在しているURIは、APIをわかりずらくさせ、間違いやすくします。なのでどちらかで統一したほうが良く、標準的には小文字が選択されています。
サーバー側のアーキテクチャが反映されていないURI
ここでいうアーキテクチャというのは、どんなソフトウェアを使用しているか、どんな言語を使っているか、サーバーサイドのディレクトリ構造がどうなっているかなどということです。URIにそれらがわかる情報を含めてしまうと脆弱性をついて攻撃を受ける可能性が高くなってしまいます。
利用者にとってはどんな言語が使われていようが関係ないので、URIにサーバー側のアーキテクチャを反映させるような設計は避けたほうがいいです。
ルールが統一されたURI
ルールが統一されたURIとはどうゆう意味かというと、例えばユーザー情報を取得するAPIがあったとします。1つはクエリパラメータにIDを入れるタイプと、もう1つはパスにIDを含めるタイプです。このように統一感がないと、利用者の混乱やトラブルを招いてしまうことがあります。なのでなるべくはルールーを統一するようにしなければいけません。
HTTPメソッドとエンドポイント
APIへのアクセス方法としてHTTPメソッドは非常に重要です。HTTPメソッドはリクエストヘッダの先頭行に含めて、サーバーに送信されます。
エンドポイントで取得できるリソース（情報）をどう操作するかがメソッドの役割です。
HTTPメソッドには以下の種類があります。
- GET・・・ 取得
- POST・・・新規登録
- PUT・・・更新
- DELETE・・・削除
- PATCH・・・一部変更
- HEAD・・・メタ情報取得
GETメソッド
情報の取得を表すメソッドです。URIで指定したリソースを取得するために用います。なのでGETメソッドでサーバー上のリソースが変更されることはありません。注意として、GETメソッドに対してサーバー側の処理を書くのはダメです。
POSTメソッド
POSTメソッドは情報を更新するものであると勘違いしがちですが、実際にはURIに属する新しいリソースを送信し、登録するために使用します。
ユーザーを登録するなどにはPOSTメソッドが最適です。
POSTメソッドで送信したデータは、指定したURIの配下に作られるというイメージです。
PUTメソッド
PUTメソッドは、更新したいリソースのURIを指定して、その内容を書き換えます。また、PUTメソッドは送信するデータで元のリソースを完全に上書きします。
DELETEメソッド
URIで指定したリソースを削除するときに使用します。
PATCHメソッド
PUTメソッドとは違い、リソースの一部を変更したいときに使用します。PATCHメソッドを使用することで、変更箇所のごく小さなデータだけを送ることができます。
できる限りハイフンを使用する
エンドポイントで単語を2つ以上繋げる必要がある場合には、いくつか方法があります。
- スパイナルケース
- スネークケース
- キャメルケース
様々なURIを調べてみると、ハイフン（スパイナルケース）を使用している割合が多く感じます。ある程度は、好みで決めてもいいと思いますが、迷った場合はハイフンにするのが妥当です。そして、なるべくなら単語を繋ぎ合わせるのは避けるべきです。パスとして区切ったり一部をクエリパラメータにするなど、なるべく短い表現になるように工夫することで、より見やすいURIになります。
おわりに
まだまだAPIについては学ぶことがたくさんあるので引き続き学習していきたいと思います。