自社で API開発する前に知らなきゃ後悔する３つの基本

APIって何？　誰が使うの？

APIとは、サービス内の情報や機能を外部に提供する仕組みのことです。

例えば、弊社のサービス「ソトミル」では Google Maps APIs の一つ、Geocoding API を利用して住所や地名から緯度経度の地理座標を取得しています。

そして、API を使う（呼び出す、呼び出される）のは、いろんな場所で動作する「プログラム」です。

APIはなんの略かというと、「アプリケーション・プログラミング・インターフェース（Application Programming Interface）」。その名の通り、プログラムの間をつなぐインターフェースなのです。

APIの正体は、YAMLファイル

「API を作れ」と言われたら、具体的に何を作ればいいのか？

答えは、「OpenAPI 構成ファイル」「OpenAPI ドキュメント（API ドキュメント）」「OpenAPI仕様書（API仕様書）」などと呼ばれる YAML ファイルです。
（以降、API ドキュメントと呼称します）

先ほど、API を使うのはプログラムだと書きました。つまり、API開発者は、提供する相手（の開発者）に API の仕様を伝え、どうやってプログラムに組み込むのかを教える必要があります。そのAPI の仕様を記述するのが、API ドキュメント と呼ばれる YAML ファイルの中ということ。

API ドキュメントを作成するには、Swagger Editer（https://swagger.io/tools/swagger-editor/）を使います。 ブラウザ上で動作するエディタで、左がYAMLファイル、右がプレビューです。編集しながら生成されるドキュメントを確認できてありがたい。

API の仕様には、例えば以下のようなものが含まれます。

• 何に対して：URL
• 何をするか：HTTPメソッド（GET、POST、DELETE、etc…）
• 何を渡すか：リクエストパラメータ
• 何を受け取るか：レスポンス

API ドキュメント を作ったら、あとは公開するだけです。

APIを公開する方法は色々考えられますが、次回、 Google Cloud の Endpoints を使った場合をご紹介します。

Open API、OpenAPIs、オープンAPI、Web API、Rest API、RESTful APIの違い

今回、API の自社開発を初めて担当したのですが、いろんな言葉が出てきて訳がわからなくなりました（笑）

調べれば調べるほど 「APIとは果たしてなんなのか、自分は何API を作ればいいのか」迷路に迷い込みました。私と同じく途方に暮れている人には、きっと以下の整理が役に立つと思います。

• WebAPI：Webを介して仕様するAPI
• Rest API（＝ RESTful API ）：RESTの考え方に従って作られる WebAPI
• オープンAPI（＝ Open APIs ）：アクセスがオープンにされているAPI
• OpenAPI：RESTful APIの標準フォーマットを推進する団体「Open API Initiative」の略称。
• Open API 2.0、Open API 3.0：「Open API Initiative」の名称変更で更新された略称。

今どき RESTful ではない API ってあまりないので、WebAPI ＝ RESTful API というざっくり理解でも問題ないと思います。

まとめ

・API とは、プログラム同士をつなぐインターフェース

・API の正体は、API ドキュメントと呼ばれる YAML ファイル

・API 関連の言葉はめちゃくちゃわかりにくい

関連記事

Cloud Endpoints を使って簡単・安全に自社サービスをAPI化する方法