サーバー、データベース、インフラに関するトピックス
■第14話：APIの設計と開発
（最終更新日：2023.09.28）
（絵が小さい場合はスマホを横に）
「APIを使ってもらうには」
APIを開発する際に重要なことは、多くの人にとって分かりやすく、使いやすいことである。
そして、そのAPI自体が有用なものであることは言うまでもない。
そのためには、明確で一貫した設計、詳細なドキュメンテーション、簡潔なAPIで開発する必要がある。
今回は、そのために必要なことを学んでいこう。
１.APIの設計原則
一貫性は、APIのエンドポイント、レスポンス、エラーメッセージが同一の形式や命名規則に従うことを意味する。 一貫性が保たれているAPIは、開発者が理解しやすく、利用しやすいため、エラーの発生率も低くなる。 エンドポイントの命名規則で言えば「名詞を使用」「複数形を使用」「階層構造を分かりやすく」である。 リソースの操作に寄り、厳密、厳格になる部分はあるが、基本的にはWeb開発におけるルーティング、URLの決め方と似ている。 下記は、エンドポイントの例である。
エンドポイントの例
次に大事なポイントは、冗長性の排除である。 不必要な繰り返しや複雑さを避け、APIのシンプルさと効率性を保つことが重要である。 これにより、開発者はAPIの機能を迅速に理解し、効果的に利用できる。
最後に大事なことは、セキュリティだ。 APIのセキュリティは非常に重要であり、データ漏洩や不正アクセスを防ぐために、様々なセキュリティ対策が必要である。 これには、SSL/TLSによる通信の暗号化や、適切な認証・認可機構の実装が含まれる。 ここでいう認証はAPIキーやアクセストークン、認可はそれによってアクセスできる場所を制限することである。 ユーザー毎、権限ごとに使えるリソースを決める。
２.APIの開発プロセス
APIの開発プロセスは、例えば以下の手順に従う。
2.1 要件定義
API開発の最初のステップは、APIの目的や機能、利用者のニーズを明確に定義することだ。
これにより、開発の方向性が定まり、効率的な開発が可能となる。
2.2 設計
要件定義を基に、APIの詳細な設計を行う。
これには、エンドポイントの設計、リクエスト・レスポンスの形式の定義、エラーハンドリングの設計などが含まれる。
2.3 実装
設計した仕様に基づき、実際のコードを書いてAPIを開発します。実装段階では、設計が正確に反映されているか注意深く確認する必要がある。
2.4 テスト
APIが正しく動作するかを確認するために、ユニットテストやインテグレーションテストを行う。
テストを通じて、バグや問題点を早期に発見・修正し、品質を確保する。
３.APIドキュメンテーション
良好なドキュメンテーションは、開発者がAPIを正しく理解し、効率的に利用するために不可欠だ。 また、ドキュメンテーションが不足していると、開発者の間での誤解や混乱が生じ、開発の効率が大幅に低下する。 良いドキュメントは、清晰かつ詳細で、APIの全ての機能とパラメータを正確に説明する。 また、具体的な使用例や、リクエスト・レスポンスのサンプル、エラーコードとその対処方法も含まれているべきである。
APIドキュメンテーション
４.認証と認可
4.1 APIキー
APIキーは、API利用者の識別やアクセス制御を行うための一般的な方法である。
APIキーは、リクエストに含まれ、APIプロバイダーによって検証される。
4.2 OAuth
OAuthは、第三者アプリケーションがユーザーの代わりにサービスにアクセスできるようにする認証・認可フレームワークである。
これにより、ユーザーは自身のアカウント情報を直接共有することなく、アプリケーションに特定のリソースへのアクセス権を付与できる。
ちなみに、ユーザーのパスワードを共有することなく、アプリケーションにAPIへのアクセスを許可することができるプロトコルがOAuth 1.0aで、
よりセキュアで柔軟性があり、利用が簡単、トークンベースの認証しているのがOAuth 2.0である。現在はOAuth 2.0が用いられる。
4.3 APIキーとOAuthの違い
APIキーはAPIの利用者を識別し利用の制御を行うものだが、
OAuthは更に進んで、特定の操作やリソースへのアクセス権限の制御も行う。
OAuthは特に、ユーザーのデータへの安全なアクセスが必要な場合に適している。
５.まとめ
APIの設計と開発においては、設計原則の遵守、適切な開発プロセスの選定、正確なドキュメンテーション、 そして堅牢なセキュリティ対策が重要である。誰もが使いやすく、長く使えるAPIを設計できるようになろう。
▼参考図書、サイト
「Web API The Good Parts」 オライリージャパン オーム社
最近話題の API の認証ってなに? ~OAuth編~
Cisco Japan Blog