APIとは？ 利用のメリットとAPI外部公開のポイントを解説

こんにちは、CTOの十川です。

NCDCではよくAPI（Application Programming Interface）の開発や、APIを活用したサービス開発を行っています。
一昔前まで、APIといえば銀行間取引や製造業のサプライチェーンといった一部の企業間連携に使うもの、もしくはTwitterなどの先進的なサービスだけが提供するものという印象でした。
当時はAPI化が大変で、どんなAPIから作っていくべきかを検討することにすごく時間を掛けていた記憶があります。

しかし、最近は状況が変わってきており、社内のシステム間連携をバッチ処理ではなくAPIを活用して行うことも珍しくありません。SaaSが提供するAPIを業務で利用することも一般的になりつつあります。

従来からよくAPIに触れていたエンジニア以外でも、APIに関心を持ちはじめた人、API公開を検討しはじめた人が増えているのではないでしょうか。
そこで、この記事ではAPIを利用するメリットから、APIを外部公開する時のポイントまで解説したいと思います。

APIとは？

API(Application Programming Interface)とは、プログラムが特定の機能やデータを利用するためのインターフェイスです。
インターフェイスとはハードウェアでいうとUSBやLANポートのような物理的なコネクタと、そこで信号をやりとりする方法の取り決めを指しますが、ソフトウェアでも同様な考え方で機能やデータにアクセスするための仕様を定義したものになります。

たとえば、ソフトウェアAで使いたい機能やデータをソフトウェアBが持っている場合に、BがAPIを公開していればAの開発者は（APIを通して）Bの機能やデータを利用できるようになります。

APIにはWindowsなどのOSが提供するものや、各プログラミング言語のライブラリが提供するものなど、さまざまなものがありますが、ここでは特にWebサービスのAPIについて記載していきたいと思います。

APIを利用するメリット

APIは、Webアプリやモバイルアプリの開発時にアプリからサーバ側の情報を呼び出すのによく用いられます。このような場合、APIはアプリとサーバを繋ぐためのもので外部に公開されませんが、APIには他にもさまざまな使い方があります。
例えば、Twitterが公開しているAPIを使ってTwitterのデータを利用したオリジナルのサービスをつくることが可能です。その他にも、ExcelなどのツールからAPIを呼び出してデータを取得したり、既存システム間の連携を自動化したりするケースでもAPIを活用できます。

近年、従来は人がやっていた「既存システムの画面からデータを読み取って他のシステムへ登録する」というような作業をRPAで自動化する取り組みが流行していますが、もしシステム側がAPIを提供していればもっと簡単に自動化できます。
ロボットに画面からの読み取りや登録という作業をさせる必要はなく、APIを通してシステム同士を連携することができるのです。

APIを公開する側のメリットはビジネスの拡大です。APIを用いることで自社システムから公開していい情報だけを安全に外部に連携できるため、自社のデータやサービスの利用者を増やす（エコシステムをつくる）ことができます。

なお、APIの概要については、以前セミナーでご紹介した内容をコラムとして公開していますので、こちらもぜひご覧ください。
資料公開｜マネージャー層向けAPI活用セミナー。最新の事例とDXへの応用手法を知る。

APIを公開する際のポイント

ここからはやや技術的な、APIを外部公開したい人向けの説明になります。

APIを外部に公開する際に「利用者が使いやすいAPI」にするにはどのようなことに気をつけたら良いでしょうか。私は以下のようなポイントがあると考えています。

1. APIの仕様がシンプルである
2. よくあるAPIの標準的な使い方に沿っている
3. 使う人のためのドキュメントが公開されている
4. 試せる環境がある

1.APIの仕様がシンプルである

やりたいことをシンプルな仕様で使えるのが良いAPIだと思います。
例として、商品を発注するという機能を画面からAPIを使用して実現する場合について考えてみましょう。

このようなケースでは、APIを2つに分けるよりもひとつにまとめた方がシンプルで良い仕様だといえます。
もちろん現実のシステムでは、在庫管理システムと発注システムが別れていることもありますので、その場合はそれぞれでAPIを用意するのか、２つのシステムへの更新処理をまとめるようなAPIを用意するのかはプロジェクトごとに検討を行います。

これは極端な例ですが、APIを利用するための前提条件は少なければ少ないほど良いと言えます。

2.よくあるAPIの標準的な使い方に沿っている

TwitterやGitHubなど広くエンジニアから利用されているAPIや、Django等のWebサービスフレームワークが生成するAPIと使い方が似ていると、利用者は新しく覚えることが少なく、導入がスムーズです。
標準的な使い方にするためには、まずはRESTfulの原則に沿うことが重要です。その他にも、エラーの返し方などいくつかのポイントが挙げられます。

RESTfulの原則

APIの設計において、RESTful APIという考え方があります。
RESTfulとは、HTTPの考え方に沿ってAPIを設計する方法です。

• リソース（データなど）に対して、ユニークな識別子（URI）を使ってアクセスできる
• リソースへの生成、参照、更新、削除（CRUD）をHTTPのPOST、GET、PUT、DELETEメソッドで行う

例えば、社員管理システムがあるとして「社員番号1024番の人の情報を参照する」場合には以下のようなURIに対してGETメソッドでリクエストを送ると、該当する社員情報を表すJSONデータが返ってきます。

同様に「社員番号1024番の人の情報を削除する」場合にはURIに対して、DELETEメソッドでリクエストを送ります。

どこまで厳密にやっているかはさておき、さまざまなAPIやフレームワークがこの考え方をサポートしているので、まずはRESTfulの原則に沿った設計を行うことで、利用者が使いやすいAPIとなります。

他にも、RESTfulにはそこまで細かくは定義されていませんが、APIの設計時に考慮したほうが良いことがあるので、ここでは重要なものを３つご紹介します。

エラーの返し方

エラーの返し方を適切に行うことで、うまくAPIを呼び出せない場合に、APIの利用方法が間違っているのか、指定しているデータが悪いのか、システム的なエラーなのか、を開発者が自己解決することができます。

REST APIでは一般的にHTTPステータスコードを適切に返すことが良いとされています。例えば次のようなものです。

• 200：OK、正常に処理ができた場合
• 400系：APIの利用側に起因する問題で使用する
• 400 Bad Request リクエストデータの異常などリクエストに問題がある
• 401 Unauthorized 認証されていない
• 403 Forbidden 権限がない
• 404 Not Found よくページが存在しない場合に使用されますが、APIの場合、指定したリソースが存在しない（前述の例だと社員番号1024の人が存在しない）場合にも使用されます
• 500系：API側に起因する問題で使用する
• 500 Internal Server Error APIの内部でエラーが発生した場合

アンチパターンとしては、全て200のレスポンスコードで返して、レスポンスの本文でエラーの内容を表現するというやり方もあります。
しかし、このやり方だとAPIごとにエラーの表現の仕方が異なるので、利用側はAPIのドキュメントを見ながらエラー処理を書いていく必要があり、あまり使いやすいとはいえません。

ページングの処理

データの一覧を取得するようなAPIの場合、データが大量になりすぎないように指定された件数ずつデータを取得するページングという処理を行います。
これも以下にご紹介するような一般的なやり方がいくつかあるので、独自で考えるのではなく、世の中で広く使われている方法を採用した方がいいでしょう。

Twitter_ページング
Pagination | Twitter Developer

Django_ページング
Pagination – Django REST framework

APIのバージョニング

一度APIを公開すると、新しい仕様のAPIをリリースするからといって、すでに利用されているAPIを簡単に廃止する訳にはいきません。
その場合、古い仕様のv1と新しい仕様のv2を並行で提供し、一定の移行期間を経てv1を廃止するという手順でバージョンアップを進めます。複数のバージョンを提供する方法も、一般的なやり方がありますので、よく使われている方法を採用するのがよいでしょう。

APIのバージョニング方法にはAPIのエンドポイント（呼び出す際のURL）にバージョンを含める方法と、リクエストヘッダーにバージョンを指定する方法がよく使われます。
いずれの場合も利用者である呼び出し側が、バージョンを指定することができます。
例えば、前者のAPIのエンドポイントにバージョンを含める方法はTwitterが採用しています。

Twitter_バージョニング
https://developer.twitter.com/en/docs/twitter-api/versioning

このように世の中でよく使われているAPIを研究し、それを参考に設計していくことで、外部のエンジニアがスムーズに利用できるAPIを提供することができます。

3.使う人のためのドキュメントが公開されている

APIを作るための設計書はどのプロジェクトでも作られていると思いますが、APIを使う人のためのドキュメントに力を入れているケースはまだまだ少ないと感じています。
また、API仕様をExcel等で独自に作成しているケースもよくあると思います。

API仕様を書くための記法についてもさまざまな標準化が行われています。
それらを採用することには以下のようなメリットがあります。

• API仕様として定義しておくべきことが決まっているので、検討の抜け漏れを防げる。それにより、APIの利用者は「〇〇の定義がされてないので作れない」といったことが起こりにくくなります。
• API仕様を書くためのツールや、仕様をHTMLに変換するツールなど簡易化するためのエコシステムが発達しており作業が楽になる。
• 各標準ともAPI仕様はテキストで記載するため、gitなどのバージョン管理ツールで差分等の管理がしやすい。（Excelの場合、どこが変更になったか探すのが大変ですよね）

いくつかあるメジャーな記法の中で、ここではOpenAPIをご紹介します。

OpenAPIはYAML、またはJSONでAPI仕様を書ける記法です。
https://swagger.io/specification/

OpenAPIの記法を全て理解していなくても、StoplightというOpenAPIをサポートしたGUIツールを使うことで比較的簡単に記述することができます。
https://stoplight.io/

作成したドキュメントはYAMLやJSONファイルをそのままAPIを利用する開発者に公開したり、ツールを使ってHTMLやPDFに出力して提供したりできます。

4.試せる環境がある

APIを使って開発する場合、ドキュメントだけを見て開発するのは非常に難しく、システムが正しく動かないリスクも高まります。そのため、できるだけ実際の環境と近い状態で動作を確認しながら開発を進められることが望ましいといえます。

開発フェーズの最初から実際にAPIを呼び出して少しずつ結合しながら進めることで、「開発が終わって結合試験をやろうと思ったら仕様の認識が違っていて全然つながらない」というような事態を防げます。
試せる環境を提供する方法としては、次のものがあります。

APIのモックの提供

実際のAPIではなく、予め定義した応答が返るモックを提供します。
当たり前ですがモックと実際のAPIの仕様が一致していなければ意味がありません。APIのモックを用意するためのツールも存在します。

テスト環境の提供

テスト用のデータベースなど実際のAPIが動作する環境を提供します。
マスタデータは予め入れておくとして、それ以外のテストデータの準備や、投入されたデータを定期的に初期化するなどの運用をどうするかについては検討が必要です。

APIやデータ連携の相談はぜひNCDCへ

NCDCでは、APIをどう設計すべきか、どんな技術を採用すべきかといったコンサルティングを含む、システム全体のアーキテクチャの策定をご支援しています。
また、アプリケーション開発者が該当技術に慣れていない場合には、技術移管を視野に入れてNCDCで用意したリファレンス実装を提供するサービスなども行なっています。
APIの活用やシステム間のデータ連携に関して課題をお持ちの方はぜひご相談ください。