APIに関するあれこれを調べでみた
API を作成する機会があり、これまでなんとなく使っていた API に関してしっかり言語化します。
API に関しての文献は書籍や Web にも大量にあるため、そちらを参考にしつつ、パクリにならないよう書いたつもりです。
API とは
単純に書くなら Application Program Interface の略。
実際に私たちが普段接しているのは Web API と呼ばれるもの。
もともとは OS とアプリケーションの通信に使われていたことから、現在の Web を介して用いられる API は Web API と呼ばれる。
この Web API の意味するところをいくつかの参考文献から引用してみた。
アプリケーション・ソフトウェアを構築および統合するための一連の定義とプロトコル
出典：1
あるソフトウェアから他のソフトウェアを制御するインターフェース（規約）
出典：2
HTTP プロトコルでやりとりするアプリケーション間のインターフェース
出典：3
つまり、アプリケーション（ソフトウェア）間でやりとりするための入り口と出口のルールのことを指している。
API 連携といった場合、暗黙的にエンドポイントがあって、そこに HTTP プロトコルでリクエストを送り、レスポンスを受け取るといった一連の操作が連想される。
このように API は Web でデータをやり取りする上での共通のインターフェースと言える。
REST API とは
REST とは（Representational State Transfer）のこと。もう少し具体的にいうと、REST は API 設計時の原則のようなものです。
「ようなもの」と曖昧な表現にしたのは REST API と呼ばれているものが必ずしも REST の原則に従っているわけではないからです。
じゃあどんなものが REST の特徴かというと以下に示す 4 つの内容が挙げられます。（※ 原著論文では 6 つらしいので厳密ではないです）
- クライアントとサーバ側のやり取りがステートレスであること
- 一意のリソースを指す指す URL
- 統一されたインターフェース（HTTP プロトコル、メソッド）
- JSON や XML などを用いた情報と状態遷移を行うことができる
設計時に気をつけること
まずは可視性です。要は API をパブリックで使うのかプライベートで使うのかです。
パブリックにする場合は認証認可方法とアクセス数増加による負荷を検討する必要があります。
プライベートで扱う場合は、認証なしでも大丈夫でしょう。パブリックにする必要がないものはネットワークに閉じたほうが開発は楽です。
あとはもうちょっと実装よりの話だと6の記事がめちゃめちゃ参考になります。
Swagger と OpenAPI とは
これに関しては Swagger の公式サイトにWhat Is the Difference Between Swagger and OpenAPI?という記事に記載がありました。
内容を自分なりに解釈すると OpenAPI とは OpenAPI Specification のことを指し、REST API を構築するためのインターフェースの仕様を定義したものです。 そして、Swagger とは OpenAPI の仕様に従った実装を行うためのツール群を指します。
Swagger のツールとは具体的に、Swagger Editor、Swagger Codegen などがあります。
これらのツールを使うことで、OpenAPI 準拠のドキュメント作成や API サーバのスタブなどが使えるようになります。
OAuth とは
ざっくりいうとサードパーティアプリに対してデータのアクセスを許可する認可の仕組み（フレームワーク）です。
OAuth は Web API を調べてるとよく出てくるワードです。
なぜよく出てくるのかというと、Web API を用いてアプリやシステム間でデータのやり取りを行う際の、認可の仕組みとして登場するからです。