まえがき
APIに関する社内の学習資料を作成することになったので、Qiitaにもその内容を載せておきます。
初心者や初学者にとって、APIという言葉は聞いたことがあるかもしれませんが、具体的にどのようなものか理解しづらいものであると思います。
この記事では、APIについての基本的な理解を深めることを目指します。本記事では、APIがどのようなものか、その重要性や設計原則についてわかりやすく解説することを目指します。
APIについて
APIとは？
APIとは「Application Programming Interface」を略した言葉で、ざっくりに言うとAPIはプログラム同士が情報をやり取りするための窓口や取り決めのようなものです。
インターフェースという言葉に着目すると、UI (User Interface)という言葉があります。こちらの方が馴染みある人も多いのではないでしょうか。
これらを比較してみるとユーザとアプリケーションの接点がUI、アプリケーションと別のアプリケーションの接点がAPIという対比になります。なんとなくイメージできましたでしょうか？
言葉の定義としては上記の通りですが、違和感を覚えている人もいるかもしれません。APIとは単なるインターフェースに過ぎないものの、実際使用されているAPIという言葉はそれ以上の意味を含んでいることが多いです。よくあるのは、APIとその内部実装、さらにそれを含んだソフトウェア製品全体を指すものとして使われます。その文脈でAPIと言われている場合に単なるAPIではなく、Web APIを指すことがありますので留意していただきたいです。
APIはソフトウェアをレゴブロックに変える
APIは、ソフトウェアを再利用可能にしやすくするための重要なツールです。その役割をわかりやすく比喩するならば、レゴブロックのようなものです。
レゴブロックは、小さなブロックが組み合わさることで様々な形や構造を作ることができます。同様に、APIも小さな部品のようなものであり、これらの部品が組み合わさることでソフトウェアを構築することができます。
例えば、レゴブロックで家を作る場合、壁や窓、屋根などの様々な部品を組み合わせて構築します。同様に、APIも様々な機能やデータの部品を提供し、開発者はこれらの部品を組み合わせて新しいソフトウェアを開発します。
APIを利用することで、開発者は既存の部品（API）を再利用して新しいソフトウェアを迅速に構築することができます。また、部品同士が互いに組み合わさるため、異なるソフトウェア間での相互運用性や連携も容易になります。
要するに、APIはレゴブロックのようなものであり、ソフトウェア開発において再利用性や拡張性を高め、より効率的かつ柔軟な開発を実現します。これにより、開発者は既存の部品を再利用しながら、素早く新しいソフトウェアを構築することができます。
APIの種類
APIにはいくつか種類がありますが、ここでは今後よく目にするであろう代表的なものを2つ紹介します。
Web API
Web APIとは、Web上で提供されるインターフェースであり、HTTPプロトコルを使用して通信を行います。ウェブAPIは、Webサービスやオンラインプラットフォームが提供する機能やデータにアクセスするための手段として広く利用されています。例えば、Google Maps APIは、開発者が地図や位置情報を自分のアプリケーションに統合するためのAPIです。
REST API
REST API（Representational State Transfer API）とは、RESTfulな設計原則に基づいて設計されたAPIのことを指します。RESTfulなAPIは、リソース（Resource）を表現し、HTTPメソッド（GET、POST、PUT、DELETEなど）を使用してリソースに対する操作を行います。REST APIは、シンプルで柔軟な設計により、さまざまなプラットフォームや言語で利用されています。例えば、TwitterのAPIは、RESTfulな設計に基づいており、ツイートの取得や投稿などの機能を提供しています。
RESTとは
REST とは、Webサービスの設計思想の1つであり、ウェブ上での情報のやり取りを効率的に行うためのアーキテクチャスタイルです。特徴としては以下が挙げられます。
- クライアント/サーバ：ユーザインタフェースと処理を分離する
- ステートレスサーバ：サーバ側でアプリケーション状態を持たない
- キャッシュ：クライアントとサーバの通信回数と量を減らす
- 統一インターフェース：インターフェースを固定する
- 階層化システム：システムを階層に分離する
- コードオンデマンド：プログラムをクライアントにダウンロードして実行する
RESTの制約に従い、RESTらしいことをRESTfulと呼びます。
APIの設計
APIの設計はなぜ重要か
APIは単なるインターフェースであるという説明をしましたが、その設計に関する書籍や文献はたくさんあります。なぜそのようなインターフェースの設計が重要視されるのでしょうか。
答えを言ってしまうと、APIはソフトウェアによって利用されることはもちろんですが、それを作るのは人間です。ソフトウェアの開発者はAPIが他の（うまく設計された）インターフェースと同じぐらいシンプルかつ便利なものであることを期待します。
うまく設計されていないインターフェースは使い勝手が悪くなることに加え、場合によっては危険ですらあります。APIに限らず、UIやリモコン・ドア等の日常的に使うインターフェースの設計が悪ければ非常にストレスを感じることが想像できるかと思います。
だからこそどのようなインターフェースの設計も重要であり、APIも例外ではありません。
APIの設計原則
APIの設計においては、いくつかの重要な原則があります。これらの原則を理解することは、効果的で使いやすいAPIを設計するために重要です。これらをすべて書き出すと一冊の本になってしまうので、以下ではその代表的なものとその概要のみ触れます。
単純明快なAPIを設計する
APIはシンプルで直感的な操作を提供することが重要です。開発者がAPIを簡単に理解し、使いやすいように設計しましょう。
不必要な複雑さや混乱を避けるために、APIの操作は明確で予測可能であるべきです。誰でも理解しやすいような命名規則や構造を採用しましょう。
予測可能なAPIを設計する
APIの操作や命名規則は一貫性があり、予測可能であるべきです。開発者がAPIの挙動を容易に予測できるよう設計しましょう。
APIのエンドポイントやパラメータの命名は、その目的や機能を明確に示すものにすることが重要です。混乱を避けるために明確なドキュメントを提供しましょう。
セキュアなAPIを設計する
アクセス制御を可能にするためAPIを適切に分割することが重要です。関連する機能やリソースをグループ化して、ユーザーごとに必要な機能のみを公開することで、不正なアクセスを防ぎます。また、最小権限原則を適用し、ユーザーには必要最低限の権限のみを付与して、不必要なデータや機能へのアクセスを制限します。
また、センシティブなデータに対処する際には、適切な暗号化やマスキングを行い、データの機密性を確保します。また、データの転送や保存時にセキュリティポリシーを遵守することが重要です。
さらに、ベースとなるプロトコルやアーキテクチャに起因するデータ漏洩の可能性にも注意を払います。例えば、HTTPでの通信時にはHTTPSを使用して、データの暗号化やセキュアな通信を実現します。また、APIの認証や認可においてセキュアなプロトコルを使用することが重要です。
柔軟性と拡張性をもたせたAPIを設計する
APIは将来の変更や拡張に対応できる柔軟性を持つ必要があります。新しい機能やリソースの追加が容易であり、既存の機能やリソースの変更が他の部分に影響を与えないように設計しましょう。
バージョン管理や拡張性を考慮した設計を行い、APIの進化に柔軟に対応できるようにしましょう。
APIを文書化する
APIの仕様や使い方を十分に文書化し、開発者がAPIを理解しやすくすることが重要です。適切なドキュメントやサンプルコードを提供しましょう。
ドキュメントは簡潔でわかりやすく、APIの機能やエンドポイント、パラメータ、レスポンスの形式などを詳細に記述することが望まれます。
まとめ
この記事では、APIの基本的な理解を深め、APIの設計についての重要な原則を紹介しました。
ただ対象読者を初学者としたので（特に設計原則まわりが）だいぶ抽象的な内容になっています。このあたりをもっと学びたいと考えている人は是非以下の参考文献を読んでみてください。