オンプレ環境でAPIを構築する際に気をつけたポイント

Last updated at 2025-02-27Posted at 2025-02-27

API（アプリケーションプログラミングインターフェース）は、システム同士をつなぐ重要な役割を果たします。
今回は、オンプレ環境でAPIを構築した際に気をつけたポイントをいくつか紹介します。

なぜオンプレ環境でAPIを構築したのか？

今回のAPIは、社内のセキュリティポリシー上、外部クラウドへのデータ保存が制限されており、また運用コストを抑えるために既存のサーバーリソースを活用する方針を採りました。そのため、クラウド環境と同等の使い勝手を実現しながら、オンプレ環境での最適なAPI設計を目指しました。

どんな環境で構築したのか？

以下のようなサーバー構成、運用ツールでAPIを構築しました。

サーバー構成
- APIサーバー：Spring Boot（Java）
- DBサーバー：Oracle Database 19c
運用ツール
- 監視ツール：Prometheus, Grafana
- CI/CD：GitLab Runner
  （社内のセキュリティポリシー上、GitLabサーバから開発環境・検証環境・本番環境のサーバへのアクセスが制限されていたため、CI/CDではリリースモジュールの作成までを実施）

API構築時に気をつけたポイント

RESTful設計を心がける
API設計を行う際、利用者が実装しやすくなるように適切な設計を心がけました。以下の点を特に重視しています。
- HTTPメソッドの適切な使用
  APIでは、リソースに対する操作をHTTPメソッドで表現します。
  具体的には、以下のように使い分けました
  - GET: データ取得
  - POST: 新規データ作成
  - PUT: データ更新
  - DELETE: データ削除
- リソースを明確に定義
  エンドポイントのURLは直感的に理解できるように設計しました。例えば、ユーザー情報のエンドポイントは/user、予約情報のエンドポイントは /reservations といった具合です。
  これにより、API利用者が迷わず利用できるようにしました。
- ステータスコードを適切に使用
  レスポンスで使用するHTTPステータスコードは、クライアントが結果を正しく理解できるように適切に使用しました。
  例えば：
  - 200: 成功
  - 400: リクエストエラー（例：パラメータ不足）
  - 500: サーバエラー
    詳細なステータスコードはこちらを参考にしました。
適切なエラーハンドリング
エラーが発生した場合、API利用者が適切に処理できるよう、一貫したエラーハンドリングを行いました。
- 一貫性のあるエラー形式
  エラーレスポンスは統一された形式で返すことで、開発者が扱いやすくしました。
  以下はエラーレスポンスの例です：
```
{
  "errors": [
    {
      "field": "user_id",
      "code": "E0001"
    },
    {
      "field": "start_date",
      "code": "E0002"
    },
    {
      "field": "end_date",
      "code": "E0002"
    },
    {
      "field": "",
      "code": "E9999"
    }
  ]
}
```
- エラーメッセージの変更対応
  画面項目の文言が変更された場合、エラーメッセージも更新する必要があります。
  そのため、エラーレスポンスには直接的なメッセージは含めず、エラーコードを中心に構成しました。
APIのバージョン管理
APIのメンテナンス中に後方互換性を保つため、バージョン管理が重要です。
新しいバージョンをリリースしても、既存のユーザーに影響を与えないようにしました。
- バージョン番号をURLに追加
  APIのURLにバージョン番号を含めることで、バージョン間の差異を明確にし、クライアントが新しいバージョンに切り替える際の混乱を避けました。
  例えば、/v1/reservations、/v2/reservations といった形で実装しました。
ドキュメンテーションを整備する
API利用者がスムーズに使えるよう、以下の内容をドキュメントに盛り込みました：
- API利用ガイド
  ユースケースごとにAPIの呼び出し手順や流れを説明しました。
  これにより、利用者はどのAPIを使うべきかを簡単に理解できます。
- API仕様書
  APIの詳細な仕様書を作成しました
  - エンドポイント: HTTPメソッドとURLを記載（例：POST /v2/reservations）
  - API概要: 各APIが提供する機能を簡潔に説明
  - リクエスト: 必須フィールドやフィールドの説明、エラーコードのリスト
  - エラー一覧: エラーコードとその説明
  - 使用例: 各エンドポイントのリクエストとレスポンスの例を記載
これにより、API利用者がすぐに使えるようになりました。
ログを追跡できるようにする
ユーザーからの問い合わせに迅速に対応できるよう、ログの追跡機能を実装しました。
これにより、問題が発生した場合でも迅速に原因を特定できます。
- トレースIDをログに出力
  アクセスログ、アプリケーションログ、エラーログにトレースIDを含めることで、リクエストがどのコンポーネントを通過したかを追跡できるようにしました。
- 問い合わせ番号としてトレースIDを使用
  レスポンスヘッダにトレースIDを返却することで、ユーザーからの問い合わせにトレースIDを使用して問題解決を迅速化しました。
  これにより、問い合わせ番号としてトレースIDが利用できるようになりました。
（参考: AWS X-Ray ドキュメント）

まとめ

オンプレ環境でAPIを構築する際は、システムが健全に動作し、ユーザーが簡単に使えるように設計することが大切です。
RESTfulな設計を心がけ、適切なエラーハンドリングやバージョン管理、詳細なドキュメントの整備を行うことで、API利用者の利便性が大きく向上します。
また、ログの追跡機能を充実させることで、問題解決の迅速化を実現できました。

これらのポイントを抑えてAPIを構築することで、システムの信頼性と保守性を高めることができました。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up