現代のシステム開発やサービス連携において、APIは欠かせない存在となっています。
データのやり取りや機能の拡張を効率的に実現する手段として、企業や開発者にとってAPIの理解と適切な設計は非常に重要です。
本記事では、APIの基本的な役割から、設計時の課題、解消するための方法を解説します。
また記事の後半では、APIの品質を高めるAPIテストの重要性やツール、運用戦略についてご紹介しますので、ぜひ最後までご覧ください。
APIとは？
1-1 APIとは
APIは、ソフトウェア同士が相互に通信し、機能やデータを共有するためのインターフェースです。
従来はローカルのOSやソフトウェアを対象としていましたが、SaaSの普及によりWeb APIも単にAPIと呼ばれることが増えています。APIが公開されることで、開発者は自社システムや他社サービスと連携し、機能の拡張やデータの取得、自動化を実現できます。
もしAPIがない場合、開発者は手動でデータを取得し、他のシステムと連携するために多くの時間と労力を費やす必要があります。スクレイピングと呼ばれる手法が用いられることもありますが、UI変更やセキュリティに対するリスクが伴います。
APIが公開されることで、開発者は必要な機能を簡単に利用できるようになり、業務の効率化や新たなサービスの創出が可能になります。
また、APIの公開は開発者だけにメリットをもたらすものではありません。
SaaS側、つまりサービス提供側にとってもメリットがあります。APIが利用されることで、他のサービスとの連携が行われ、エコシステムの拡大や他社との差別化につながります。
そして、API連携を通じて事業提携につながるケースも少なくありません。
SaaS事業者でユーザーのニーズをすべて満たすのは不可能であり、ユーザーのニーズに答えるためにもAPIは重要な役割を果たします。
1-2 APIの役割
APIの役割としては、いくつかの段階があります。
最も簡単なのは、「認証なしでデータを公開する」ものです。これはブログのRSSフィードなどが該当します。
次に、「認証を行い、特定のユーザーに対してデータを公開する」ものがあります。これは、ユーザーが自分のデータを取得するためのAPIです。さらにAPIファーストの考えが進むと、APIを通じてデータの作成や削除にも対応します。
こうしたデータのCRUD（Create, Read, Update, Delete）をAPIで実現するためには、認証や認可（どの機能を使えるかの制御）を行う必要があります。
API設計の主な5つの課題
APIを設計する中での、よくある課題としては以下のようなものがあります。
- APIの設計が複雑化し、一貫性がない
- APIのバージョン管理が難しい
- APIのエラーハンドリングが不十分
- APIのセキュリティ設計が困難
- APIのテストが不十分で、リリース後にバグが発生する
それぞれ詳しく解説します。
2-1 APIの設計が複雑化し、一貫性がない
APIの設計にはいくつかのベストプラクティスがあります。多くの場合、初期の設計ではそうしたベストプラクティスに則って行われるのですが、ワークフローの拡充によって、APIの設計が複雑化します。
特に、APIの設計が複数のチームや開発者によって行われる場合、各チームのスタイルや考え方が異なるため、一貫性を保つことが難しくなります。
2-2 APIのバージョン管理が難しい
APIのバージョン管理は、特に大規模なシステムやサービスにおいて重要です。APIの変更が他のシステムやサービスに影響を与える可能性があるため、適切なバージョニング戦略が必要になります。
しかし、APIのバージョン管理は複雑であり、特に後方互換性を保つことが難しい場合があります。カラムを一つ追加しただけでバージョンを上げるのか、変更のないモデルに対してもバージョンアップを適用するのかなど、悩ましい問題が多くあります。
2-3 APIのエラーハンドリングが不十分
APIのエラーハンドリングは、APIの信頼性を高めるために重要です。エラーが発生した場合においても、適切なエラーメッセージやステータスコードを返すことで、開発者は問題を特定しやすくなります。
しかし、システムで発生するエラーは多岐に渡り、すべてのエラーに対して最適なハンドリングが行われていないケースも多数あります。その結果、503などの汎用的なエラーが返却され、開発者が問題を特定できないことがあります。
2-4 APIのセキュリティ設計が困難
APIは、外部からアクセスされるため、セキュリティ設計が重要になります。特に、個人情報や機密情報を扱う場合、適切な認証や認可の実装が必要です。認証認可はもちろん、多重アクセスに対する処理や、不正なアクセスに対して十分な対応が求められます。
しかし、こうしたAPIに対するセキュリティリスクは多様化しており、セキュリティの設計は簡単ではありません。新たな脅威に対して適切な対策を講じる必要があります。
2-5 APIのテストが不十分で、リリース後にバグが発生する
APIはシステム間連携に用いられることが多いため、一度組み上がったシステムは常時問題なく動き続けることが求められます。そのため、APIのテストが十分に行われていないと、リリース後にバグが発生する可能性があります。
APIのテストは、単体テストや統合テスト、E2Eテストなど、さまざまなレベルで行う必要があります。そのため、十分なテストが行われていない場合、リリース後に問題が発生してしまいます。
API設計の効果的な6つの方法
API設計において、すでにある効果的な方法（ベストプラクティス）を参考にしましょう。
以下に、API設計のベストプラクティスを6つ解説していきます。
- RESTful APIの原則に従う（RESTful APIの場合）
- GraphQLの活用
- OpenAPIやSwaggerを利用したドキュメント作成
- OAuth 2.0などの認証・認可の実装
- API Gatewayの活用
- バージョニング戦略の策定
3-1 RESTful APIの原則に従う（REST APIの場合）
APIをRESTで提供するならば、RESTful APIの原則に従って設計しましょう。
RESTful APIは、リソース指向の設計原則に基づいています。リソースはURIで一意に識別され、HTTPメソッド（GET、POST、PUT、DELETEなど）を使用して操作を指定します。
これにより、APIの設計がシンプルで直感的になります。
RESTful APIのアーキテクチャ設計においては、以下が参考になります。
＞What is REST API?
- クライアント・サーバー・アーキテクチャ
UIとデータ処理を分離し、UIの移植性やサーバーの拡張性を保証します。
また、コンポーネントが独立して開発でき、異なるドメイン間でも柔軟に連携できるべきです。 - ステートレス
サーバーは状態を持たず、必要な情報はすべてクライアントから送られます。
状態管理はクライアントまたは外部サービスで行います。 - キャッシュの可否
レスポンスはキャッシュ可能かを明示する必要があります。適切なキャッシュは通信回数を減らし、性能とスケーラビリティを向上できます。 - 階層化されたシステム
クライアントは途中のサーバー（プロキシやロードバランサー）を意識せずに通信します。これにより負荷分散やセキュリティ強化、柔軟な構成が可能になります。 - オンデマンドコード（任意）
サーバーはJavaScriptなどのコードを送って、クライアント側の機能を一時的に拡張できます。 - 統一されたインターフェース
一貫した設計により、開発者が一つのAPIに慣れれば、他のAPIもスムーズに扱えるようになります。
3-2 GraphQLの活用
RESTful APIと同様に用いられているのがGraphQLです。
GraphQLは、Facebookが開発したAPIクエリ言語であり、クライアントが必要なデータを指定して取得できる柔軟性があります。これにより、過剰なデータの取得や複数のAPI呼び出しを避けることができます。
RESTful APIでは結果が統一されているため、1つの変更がすべてのクライアントに影響を及ぼします。
一方、GraphQLでは、クライアントが必要なデータを指定するので、必要な場面で必要なデータだけを取得できます。
これにより、APIの変更がクライアントに与える影響を最小限に押さえられるのがメリットです。
3-3 OpenAPIやSwaggerを利用したドキュメント作成
APIのドキュメントとしてOpenAPI Specification（OAS）やSwaggerが知られています。
これらのドキュメントはDocstring（ドキュメンテーション文字列）やJSDocなどの形式でシステムコード内に記述され、APIドキュメントとして生成されます。こうした共通フォーマットのドキュメントは再利用可能であり、開発用モックサーバーの生成や、APIのテストに利用できます。
また、ドキュメント内でAPI実行をテストできる仕組みなど、APIの利用を促進するための機能も充実しています。
OASやSwaggerの活用により、APIのエンドポイントやリクエスト・レスポンスの形式を視覚的に確認でき、開発者がAPIを理解しやすくなります。
3-4 OAuth 2.0などの認証・認可の実装
APIのセキュリティでよく使われるのはOAuth 2.0やOpenID Connectです。
OAuth 2.0は、リソースオーナー（ユーザー）がクライアントアプリケーションに対して、リソースサーバー（API）へのアクセスを許可するためのプロトコルです。これにより、ユーザーは自分のパスワードを共有することなく、他のサービスと連携できます。
OpenID Connectは、OAuth 2.0を拡張した認証プロトコルであり、ユーザーの認証情報を取得するために使用されます。これにより、APIはユーザーの認証情報を安全に取得でき、セキュリティを高めることができます。
デファクトになっているこれらの技術には多くのライブラリが存在し、開発者がスムーズにAPIを利用し始められるメリットがあります。
3-5 API Gatewayの活用
API Gatewayは、APIのエンドポイントを一元管理するためのサービスです。
API Gatewayを使用することで、APIの認証や認可、トラフィック管理、キャッシュ、モニタリングなどを一元的に管理できます。これにより、APIのセキュリティやパフォーマンスを向上させることができます。
APIを安全に公開するためにも、API Gatewayは重要な役割を果たします。
3-6 バージョニング戦略の策定
APIは一度公開すれば終わりではなく、常にアップデートが行われます。そのため、APIのバージョニング戦略を策定することが重要です。
バージョニング戦略には、URL方式（例：/v1/resource）やヘッダー方式（例：Accept: application/vnd.example.v1+json）などがあります。
どちらの方式にもメリットとデメリットがあるため、プロジェクトの要件に応じて選択する必要があります。
バージョニング戦略を策定する際には、以下の点を考慮しましょう。
- バージョン番号の付け方（メジャー・マイナー・パッチ）
- バージョンの非互換性をどのように扱うか
- バージョンの廃止やサポート終了の方針
- バージョン間の互換性を保つためのルール
- バージョン間の移行手順やドキュメントの整備
APIの品質を保証する「APIテスト」の重要性
APIにおいても、テストは重要です。APIのテストは、APIの品質を保証し、リリース後のバグを防ぐために行われます。APIのテストには、単体テスト、統合テスト、E2E（End-to-End）テストなどがあります。
通常のWebブラウザからのアクセスの場合、システムを更新した場合には、ユーザーは最新のUIに触れ、最新の仕様にあったデータを送受信します。しかし、APIの場合は違います。すでにローンチしているシステムがあり、過去のAPIに沿ったリクエストを送り、過去のAPIに沿ったレスポンスを期待されます。そのため、APIの後方互換性が常に求められます。
APIのテストは、以下のような目的で行われます。
- APIの機能が正しく動作することを確認する
- APIのパフォーマンスやスケーラビリティを評価する
- APIのセキュリティを確認する
- APIのエラーハンドリングが適切であることを確認する
- APIのドキュメントが正確であることを確認する
APIはユーザー（人）ではなく、システム（プログラム）からの利用を想定しています。
そのため、テストの自動化がしやすいというメリットがあります。過去のバージョンを対象にしたテストも残しておき、常にテストが成功するように開発されなければなりません。後方互換性を維持し、新しいバージョンをリリースするためには、APIのテストが欠かせません。
レスポンス構造の変更は、利用者側のシステムで不具合を起こす可能性があります。項目の追加はローリスクですが、削除や名前の変更はリスクが大きくなります。さらに、文字列から配列への変更などは、互換性の問題につながりやすいでしょう。
APIが更新され、徐々に複雑になっていくとパフォーマンスの問題が出てきます。APIのテスト時には、実行速度を記録しておき、パフォーマンスが許容値内に収まっているかを確認する必要があります。また、APIは多くのシステムから連続してアクセスされることが多いため、多重アクセス時のパフォーマンスにも注意が必要です。
APIのセキュリティは、データの追加・更新・削除を伴うAPIを公開している場合において、特に重要です。データの公開のみであっても、他人のデータを閲覧できないよう、適切に制御されているか確認する必要があります。APIのセキュリティは、認証や認可の実装、データの暗号化、アクセス制御など、多岐にわたります。
APIドキュメントは常に正確性が求められます。SwaggerやOASは、ベースになるドキュメント（JSONやYAML）からテストを生成する機能があります。そうした機能を用いることで、ドキュメントと実際に動作するシステムとの差違を確認できます。
APIテストに活用できる便利なツール6選
APIのテストには、さまざまなツールが利用できます。以下に、代表的なAPIテストツールを6つご紹介します。
- Postman
- Step CI
- Karate
- Tavern
- Dredd
- runn
5-1 Postman
Postmanは、APIのテストやドキュメント作成に特化したツールです。
APIのリクエストを簡単に作成でき、レスポンスを確認できます。また、テストスクリプトを記述することで、自動化されたテストを実行できます。
NewmanというPostman製のツールにより、CI/CDパイプラインに組み込むことが可能です。
5-2 Step CI
Step CIは、APIテストを自動化するためのツールです。
APIのリクエストやレスポンスをYAMLで定義し、テストケースを作成できます。また、CI/CDパイプラインに組み込むことができ、継続的なテストが可能です。
5-3 Karate
KarateはJavaベースのDSLを用いたAPIテストフレームワークで、BDD（ビヘイビア駆動開発）スタイルの記述により、エンジニア以外の方でも理解しやすいテストコードを作成できます。
REST APIやGraphQL、WebSocketのテストに加え、UIテストやパフォーマンステストもサポートしています。
5-4 Tavern
TavernはPythonベースのAPIテストフレームワークで、YAML形式でテストケースを定義できます
TavernはRESTful APIやGraphQL、MQTT、gRPCなどのテストに対応しています。
5-5 Dredd
Dreddは、OpenAPIやAPI Blueprintの仕様書から自動的にテストを生成し、APIの実装が仕様通りであるかを検証するツールです。Node.jsですが、他のさまざまな言語と連携できます。
5-6 runn
runnは、YAMLベースでAPIのシナリオテストを記述します。シナリオが書きやすく、エンジニア以外の方でも記述できます。そして、作成したYAMLをそのままテストとして実行できます。
拡張性と保守性を見据えたAPIの運用戦略ポイント
APIは作って終わりではありません。システムの成長に合わせた拡張があり、利用される限り保守性が求められます。APIの運用戦略のポイントをご紹介します。
6-1 ドキュメント更新
APIのドキュメントを常に最新状態に保つためには、コードとドキュメントの距離を縮めるのが重要です。
ドキュメンテーション文字列を利用し、コード内にドキュメントがあることで、ドキュメントの更新漏れを防ぐことができます。
6-2 バージョン管理
APIのバージョン管理は主に「URL方式」と「ヘッダー方式」の2パターンがあります。
URL方式の中にも、パスに持たせる方式とクエリパラメータに持たせる方式があります。
どちらの方式を選ぶにせよ、細かな制御はAPIの複雑性を増し、保守性を低下させます。
自社に合ったバージョン管理戦略を策定し、運用していくことが重要です。
6-3 セキュリティ対策
APIは外部システムからのアクセスを前提としているため、セキュリティ対策が常に求められます。セキュリティホールがあれば、あっという間にデータを盗まれたり、改ざんされたりします。
自社で十分なセキュリティ対策が行えるという確証がある場合は良いですが、そうでない場合はAPI Gatewayなどのサービス利用を検討しましょう。
6-4 ログ・モニタリング
APIログは、APIの利用状況やエラーのトラブルシューティングに役立ちます。アクセス頻度を見ることで、システム修正による影響や、適切な利用が行われているかを確認できるでしょう。逆にエラーが増えている場合やアクセスがスパイクした場合には、早急な対応が必要です。
6-5 テスト自動化
APIは人手によるテストが難しいため、システムに組み込んだ上でのテスト自動化が重要です。CI/CDパイプラインに組み込み、APIの変更があった場合に自動でテストが実行されるようにしましょう。テストを十分に行うことで、品質の高いAPIを提供できます。
まとめ
APIとは、システム間連携やサービスのスケーラビリティを実現する強力な仕組みであり、その設計や運用には高い品質と継続的な改善が求められます。
複雑化するAPI環境においても、適切な設計指針やテスト体制、運用戦略を取り入れることで、安全で拡張性の高いAPIの提供が可能になります。
バルテスでは、SaaSにおけるAPIテストの支援を提供しています。API運用に課題を感じているご担当者の方は、ぜひお気軽にご相談ください。
APIの設計や運用に関するベストプラクティスを参考にし、APIの品質を向上させていきましょう。