API開発の基礎知識
今回の記事は私が学んだ内容をベースに、ChatGPTの新機能Canvasを使ってまとめています。
1.いろんなサービスで活用されるAPI
インターネットやアプリケーションの世界で、よく使われる技術であるAPI（Application Programming Interface）。
例えば、人材系企業の転職サイトでは、外部プラットフォームから応募者データをAPIを通じて取得し、自社のシステムに連携する仕組みが一般的です。
【例】indeedとリクナビNEXT
● indeed(外部プラットフォーム）
⚪︎ 転職者がindeedから求人応募
⇩
API
⇩
● リクナビNEXT（転職サイト）
⚪︎ 応募者データを自システムに取り込む
この仕組みがなければ、応募者データの手動入力や更新に多大な時間がかかかります。
しかし、APIを活用することで異なるシステム間でのデータ連携が効率化され、応募情報の管理や運用が格段にスムーズになります。
今回はAPI開発の基礎知識についてまとめてみたいと思います。
2.そもそもAPIとは？
APIとは？
API（Application Programming Interface）とは、異なるソフトウェアやサービスがデータをやり取りするための窓口のようなものです。
平たく説明するとUIは人とソフトウェアをつなぐ窓ですが、APIはソフトウェアとソフトウェアをつなぐ窓です。
例えば、人材サービスにおいては、ある転職プラットフォーム（例：転職会議）が保有する応募者データを、別のプラットフォーム（例：リクナビNEXT）に渡すためにAPIが利用されます。
これをイメージしやすい例で説明すると、APIは"電車の乗り換え案内"のような役割を果たします。
乗り換え案内が複数の鉄道会社から運行情報を集めて乗客に最適なルートを提供するように、APIも異なるシステム間で必要なデータをやり取りします。
開発現場で使われる「API」という言葉の定義に注意
上記で記載の通りAPIの本来的な定義はインターフェースです。
しかし、開発の現場では「2つのサービス間でデータを加工して出力する仕組み」や、「受け取ったデータを取り込む部分」まで含めてAPIと言っているケースがあります。
私自身がマーケティング担当として、初めてAPI開発プロジェクトに関わった時にこのあたりが綺麗に整理できずモヤモヤした経験がありました。
3.APIを通じてやりとりできる様々なデータ形式
APIを通じたデータのやり取りにはさまざまなデータ形式が利用されます。
代表的なものとして、JSON（JavaScript Object Notation）、XML（Extensible Markup Language）、CSV（Comma-Separated Values）などがあります。
その中でも、JSONは以下の３つの理由から非常によく使われる形式です。
①軽量で効率的
JSONはテキストベースで軽量なため、ネットワーク通信の負担を最小限に抑えます。
②可読性
人間にも読みやすく、構造が直感的であるため、開発者にとって扱いやすい。
③広範な対応性
多くのプログラミング言語やツールがJSONをネイティブでサポートしている。
私が関わってるサービスもJSONデータを扱うことが多い気がします。
一方で、場合によってはXMLやCSVも利用されます。たとえば、XMLはデータの階層構造が複雑な場合や、レガシーシステムとの互換性が求められる場合に使用されます。
また、CSVはテーブル形式のデータを効率的にやり取りしたい場合に使われることがあります。
それでもJSONが一般的に選ばれる理由は、そのシンプルさと幅広い対応性にあります。
例えば、下記はサンプルですが転職会議からリクナビNEXTが応募者データを取得するとき、以下のようなJSONデータが返ってくる場合があります。
ちなみにJSONは非構造化データ（表形式ではないがデータに規則性がある）と呼ばれています。HR領域ではテーブル形式に整理されていない情報を多く扱うため、活用機会が必然的に多くなっていると想定されます。
4.HTTPとHTTPメソッドの基本（GETとPOST）
APIは通常、HTTP（HyperText Transfer Protocol）というプロトコルを通じてデータをやり取りします。
HTTPとは、インターネット上で情報を送受信するためのルールの集合です。
このプロトコルを使うことで、クライアント（利用者のアプリケーション）とサーバー（データを持つシステム）が効率的に通信できます。
たとえば、リクナビNEXT（クライアント）は、応募者情報を取得するためにAPIを利用して転職会議（サーバー）にリクエストを送ります。
転職会議はそのリクエストに応じて応募者情報を検索し、リクナビNEXTに返信（レスポンス）を返します。
この仕組みにより、リクナビNEXTは転職会議のデータをスムーズに利用することができます。
なお、"リクエスト"はクライアントからサーバーに送る通信のことを指し、サーバーからクライアントに返される通信は"レスポンス"と呼ばれます。
HTTPには複数のメソッド（クライアントとサーバーが通信する際に使用する指示）がありますが、APIでよく使われるのは以下の2つです。
①GET
サーバーからデータを取得するためのリクエスト。例えば、応募者リストを取得する場合に使用します。
ex.リクエスト例
応募者情報を一覧で表示したいとき等
②POST
サーバーにデータを送信して新しいリソースを作成するためのリクエスト。例えば、転職会議が応募者データをリクナビNEXTに送信する際に使用されます。
ex.リクエスト例
5.POSTリクエストとレスポンスの仕組み
個人的なPOSTリクエストとレスポンスの関係性が分かりにくかったので整理したいと思います。
POSTは「クライアントからサーバーにデータを送信して新しいリソースを作成する」というリクエストメッセージです。
その後、サーバーがそれに応答して処理結果をクライアントに返します。この返されるメッセージが「レスポンス」です。
ですので、「POSTリクエスト」はあくまで通信の最初の部分（クライアントがサーバーに送信する部分）を指します。
一方、「レスポンス」はそのリクエストに対する応答であり、別のプロセスとして扱われます。
6.Webhookの活用：リアルタイム通知
Webhookは、APIが自発的に外部システムにデータを送信する仕組みです。
人材サービスでは、応募が完了した瞬間に自社システムに通知を送る仕組みとしてWebhookが役立ちます。
例えば、転職会議で応募が完了したときに以下のような通知がリクナビNEXTのサーバーに送られることがあります。
Webhookの設定により、応募データをリアルタイムで取得し、迅速に次のアクション（例：応募者への自動返信メール送信）を実行できます。
7.API開発の手順
本項ではAPI開発の大枠の手順についてまとめていきたいと思います。
1. 目的の明確化
APIを開発する理由を明確にします。どのような課題を解決するのかを具体的にします。
【例】転職サイトがAPIを活用する場合
転職サイトでは、応募者情報をリアルタイムで取り込む必要があります。この場合、「応募者データの連携」がAPI開発の目的になります。
2. 要件定義
APIが実現すべき機能や性能、セキュリティ要件を決めます。
● 主な要件例
⚪︎ データ形式
▪︎APIで使用するデータ形式を選定
⚪︎ 通信方法
▪︎GETやPOSTなどのメソッドを活用
⚪︎ 認証方式
▪︎APIキーやOAuth 2.0を使用
【例】転職サイトが外部プロットフォームから応募者データを取得する
応募者データを取得するAPIでは、名前や応募日時などの情報をJSON形式で返す仕様を定義します。
3. API設計
APIで提供する機能を具体的に設計します。
● エンドポイント（APIがアクセスされるURLを定義します）
⚪︎ GET /applicants → 応募者リストを取得
⚪︎ POST /applicants → 新しい応募者を登録
● 結合表
⚪︎ API設計を整理するために結合表を作成
4. データ構造とモデリング
APIで扱うデータの構造を設計します。例えば応募者データを扱うAPIの場合、JSON形式のスキーマを以下のように定義します。
データの階層構造や関係性を明確にし、必要に応じてER図やUML図で表現します。
5. 実装とテスト
設計に基づいてAPIを実装し、テストを行います。
● 使用するツールの例
⚪︎ Postman（ポストマン）
▪ 作成したAPIの動作確認やテストに利用します。
⚪︎ ngrok（エングロック）
▪ ローカル環境を一時的に外部公開してWebhookなどの動作確認を行います。
● テストの種類
⚪︎ ユニットテスト
▪︎APIの各機能が正しく動作するか？
⚪︎ 統合テスト
▪︎複数の機能が連携して動作するか？
⚪︎ 機能テスト
▪︎エンドポイント全体の動作を確認します
⚪︎ パフォーマンステスト
▪︎ 多数のリクエストを処理できるか？
⚪︎ セキュリティテスト
▪︎ データが安全に保護されているか？
6. デプロイと運用
テストが完了したAPIを本番環境に配置して運用を開始します。
● 運用上のポイント
⚪︎ エラーログの確認
▪ 問題発生の際、原因特定のため確認
⚪︎ アップデート
▪ 新機能を追加 | セキュリティ対策強化
7. 認証方式とセキュリティ
APIの安全性を高めるために認証方式を導入します。
● APIキー
⚪︎ 公開しないように注意
▪ リポジトリやフロントエンドコードに含めない
⚪︎ 利用可能なIPアドレスや権限を制限
●OAuth 2.0
⚪︎ アクセストークンの有効期限を短く設定し、リフレッシュトークンを使用します
⚪︎ 必要最低限の権限（スコープ）を付与します
API開発は、目的の明確化から運用までの段階を一つずつ進めることで、安全かつ効率的なシステムを構築できます。
8.API開発時に留意したい点：外部プラットフォーマー（例：転職会議）から応募者データをAPIでリクナビNEXTに送付する場合、両者がAPIを用意すべきか？
あくまで例として考えてみます。
外部プラットフォーマー（例：転職会議）から応募者データをAPI経由で転職サイト（例：リクナビNEXTに）に送付する場合、以下の点を考慮する必要があります。
どちらもAPIを用意しなければならないかは、各サービスのシステム設計と要件次第です。以下に詳しく説明します。
1.APIの役割
転職会議の役割
応募者データを提供するAPI（アウトバウンドAPI）を用意する必要があります。
応募者データ（氏名、連絡先、履歴書など）を適切な形式で出力するため。
必要であれば、リアルタイムで送信する仕組み（Webhook）を提供する場合もあります。
リクナビNEXTの役割
データを受け取るAPI（インバウンドAPI）を用意する必要があります。
応募者データをリクナビNEXTのシステムに取り込む仕組み。
データ形式の整合性や認証・権限管理を考慮。
2. APIの両者が必要なケース
両者がAPIを用意する必要がある場合
データの自動連携が必要な場合、両サービスが以下を整備する必要があります。
転職会議側：応募データを送信するAPIまたはWebhookを提供。
リクナビNEXT側：応募データを受け取るAPIエンドポイントを提供。
例
転職会議は応募者データをPOSTリクエストで送信。リクナビNEXTはそのデータを受け取り、自システムに登録。
3. APIを片方だけ用意する場合
状況によっては、片方だけAPIを用意することも可能です。
転職会議側のみAPIを用意する場合
リクナビNEXTが転職会議の提供するAPIをコールする形。
リクナビNEXTが応募者データを定期的に取りに行く（Pull型）。
例: GET /candidates APIでデータを取得。
リクナビNEXT側のみAPIを用意する場合
転職会議が応募者データをPOSTリクエストで送信する（Push型）。
その際、転職会議がリクナビNEXTのAPI仕様に従う。
結論
両者がリアルタイムかつシームレスに連携する場合、基本的には両方のプラットフォームがAPIを用意する必要があります。
ただし、以下の点を確認してください：
どちらが主導権を持つのか（Pull型 or Push型）。
コストや実装の手間を考慮して、API以外の連携方法が適しているか。
具体的な要件次第では、外部の連携サービスやプロトコルも選択肢に入ります。
8.参考にした記事まとめ
API開発の勉強にあたり参照した記事を貼っておきます。