外部APIの仕様が不明確な案件でも、バックエンド部分を外注できるのか
- 2 日前
- 読了時間: 12分
顧客案件で外部APIとの連携が必要になったものの、仕様書だけでは実際の挙動が分からない、テスト環境で確認しなければ判断できない、提供元への問い合わせも必要になる。こうした案件でも、バックエンド部分を外注することは可能です。
ポイントは、顧客要件だけでなく、第三者であるAPI提供元の仕様そのものが不確定要素になることを前提にすることです。不明点を含んだまま実装一式を固定価格の請負にするのではなく、まず調査工程を切り出し、実装できる状態まで整理してから開発へ進みます。
はじめに：API仕様書があっても、実装に必要なことが全部分かるとは限らない
SIerやWeb開発会社が顧客案件を進めていると、外部サービスとのAPI連携だけが不確定要素として残ることがあります。
たとえば、
API仕様書は提供されているが、実際の挙動まで読み取れない
テスト環境で動かしてみなければ判断できない
Webhookなど非同期処理の詳細が分からない
顧客システムと外部サービス側のデータをどう対応付けるか決まっていない
API提供元への確認事項が複数残っている
サポートへ問い合わせているが、回答待ちで案件が進まない
といった状態です。
API連携を外注するときの基本的な確認事項は、API連携開発を外注するときに確認すべきポイントで整理しています。
本記事で扱うのは、さらに一歩踏み込んだケースです。
APIそのものに分からない部分があり、発注側だけでは仕様を確定できないとき、どう外注すればよいかを考えます。
結論は、すべての仕様が判明するまで待つ必要はありません。
ただし、最初から実装範囲を確定するのではなく、分からないことを調べて実装可能な状態へ変える工程から外注するのが現実的です。
結論：不確定なAPI案件は「調査」と「実装」を分ける
外部APIの不確実性が大きい案件では、次の2段階に分けると進めやすくなります。
第1段階：API仕様確認・技術調査
まず、
現在入手できるドキュメントを確認する
テスト環境で実際にAPIを動かす
顧客システムとAPIのデータ対応を整理する
非同期処理やWebhookの有無を確認する
不明点を切り分ける
API提供元への問い合わせ事項を整理する
実装できる範囲と、未解決の範囲を分ける
ところまで進めます。
不確実性が大きい場合、この工程は準委任または小さな個別契約として先行させる方法があります。
第2段階：確定した範囲を設計・実装する
調査によって連携方式が見えてきたら、
実装対象
成果物
対象外
顧客・元請・外注先・API提供元の責任分界
試験方法
検収条件
を整理し、成果物単位の請負開発へ移します。
外部サービスが絡む案件では、誰が何を確認し、どこから先を誰が責任を持つのかも重要です。責任分界については、バックエンド開発を外注するとき、責任分界はどう決めるべきかで詳しく解説しています。
つまり、API仕様が分からないから外注できないのではありません。
API仕様のどこが分からないのかを調べるところから外注するという選択肢があります。
筆者の経験では、API仕様書だけを信じて実装を進めるのは難しい
筆者はこれまでさまざまな外部API連携を扱ってきましたが、経験上、仕様書だけを読めば実装に必要なことがすべて分かるケースばかりではありません。
インターフェースの定義、パラメータ、レスポンス形式などは仕様書で確認できても、
実際にはどのタイミングで状態が変わるのか
特定条件でどのようなレスポンスになるのか
ドキュメントに明記されていない組み合わせでどう動くのか
APIと実際の業務フローをどう対応付けるのか
といった部分は、実際に動かして初めて分かることがあります。
そこで必要になるのが、自分たちで細かく試し、結果を観察し、不明点を切り分ける作業です。
もちろんAPI提供元のサポートも活用します。
ただし、問い合わせればすぐにすべて解決するとは限りません。回答に時間がかかったり、質問の意図が十分に伝わらず、やり取りを繰り返したりすることもあります。
そのため筆者が外部APIを調査するときは、単に「このAPIはどういう仕様ですか」と問い合わせるのではなく、まずこちらで可能な範囲を検証します。
たとえば、
この条件でこのリクエストを送信すると、このレスポンスになった。別の条件ではこの結果になった。仕様書のこの記述からはAと解釈しているが、実際の結果はBに見える。この場合、期待する動作はどちらか。
というところまで状況を整理したうえで、確認したい点をピンポイントにしてサポートへ問い合わせます。
遠回りに見えますが、この方が問題の所在を特定しやすく、回答も得やすくなります。
外部API連携では、コードを書く技術だけでなく、再現条件を作り、挙動を観察し、不明点を切り分け、第三者へ正確に問い合わせる力が必要になります。
これは、経験と根気が必要な工程です。
仕様が不明確なときに調べるべき4つのポイント
一般的なAPI発注時の確認事項を繰り返すのではなく、仕様が不明確な案件では特に次の4点を確認します。
1. テスト環境で、実際にどこまで再現できるか
まず確認したいのは、資料の量よりも実際にAPIを試せるかです。
たとえば、
テスト環境
テストアカウント
APIキーなどの認証情報
テストデータ
接続元IPアドレス等の制限
が用意できれば、仕様書だけでは分からない部分を実際の結果から確認できます。
反対にテスト環境が利用できない場合は、何を本番前に確認できず、どの部分に不確実性が残るのかを明確にします。
「テスト環境がない」という事実も、重要な調査結果です。
2. 顧客システムと外部APIのデータをどう対応付けるか
APIを呼び出せるだけでは、連携は完成しません。
たとえば外部サービスに、
顧客ID
取引ID
商品ID
ステータス
が存在するとします。
それぞれを顧客システム側のどのデータと対応付けるのかを決める必要があります。
ここで重要なのは、APIの項目名を読むことではありません。
後から「この外部サービス上のデータは、顧客システムのどの処理に対応するのか」を追跡できるようにすることです。
外部API側の仕様と、顧客システム側の業務・データモデルの両方を理解しながら整理します。
3. 非同期処理・Webhookを含め、結果をどこで確定するか
外部APIによっては、リクエストを送った時点で最終結果が返らないことがあります。
たとえば、
APIへ処理を依頼する
外部サービス側で処理する
後からWebhookで結果が通知される
という構成です。
この場合、
API呼び出し直後に顧客システムをどの状態にするか
Webhookをどこで受信するか
どのデータと紐付けるか
通知が来なかった場合にどう確認するか
といった設計が必要になります。
単純なAPIリクエスト・レスポンスだけを見ていると、この部分を見落としやすくなります。
4. API提供元へ「誰が、何を」問い合わせるか
仕様が不明確な案件では、API提供元とのコミュニケーションも開発工程の一部です。
最初に、
元請側から問い合わせるのか
エンド顧客から問い合わせるのか
外注先が直接問い合わせ可能なのか
技術的な質問文を誰が作るのか
を決めておきます。
外注先が直接問い合わせできない場合でも、「この条件でこの結果になっているため、この点を確認してください」という質問文まで技術側で整理できます。
問い合わせ窓口を持っていることと、適切な質問を作れることは別です。
API調査では、後者を誰が担当するのかが重要になります。
「見積できるか」ではなく、4つの状態に分けて判断する
当社では、見積前に情報の確度を確認し、案件を大きく4つに分けて考えています。
見積OK
連携範囲、成果物、検収条件、責任分界などが概ね確定している状態です。
この場合は、通常どおり実装工程の見積へ進めます。
条件付き
一部に未確定事項はあるものの、前提条件として明記すれば、実装範囲と金額を決められる状態です。
調査先行
APIの実際の挙動や連携方式など、工数・責任・納期へ影響する不確定要素が大きい状態です。
この場合は、無理に実装費を固定せず、有償の技術調査や仕様整理を先行させます。
外部APIの仕様が不明確な案件は、多くの場合この区分から始めます。
保留
そもそも、
利用するAPIが提供されているか分からない
API利用契約の見通しがない
テスト手段も問い合わせ手段もない
顧客側でも何を実現したいのか決まっていない
など、調査を始める前提そのものが不足している状態です。
この場合は、まず不足している情報や条件を確認します。
重要なのは、「分からないから見積不可」で終わらせないことです。
見積OK、条件付き、調査先行、保留のどこにいるのかを整理すれば、次に何を確認すべきかが見えてきます。
具体例：配送サービスとのAPI連携で、仕様書だけでは判断できない場合
たとえば、顧客のECシステムから外部の配送サービスへ出荷情報を登録するAPI連携を考えます。
仕様書には、
出荷登録API
配送状況取得API
が掲載されているものの、実際の案件では次のような疑問が残っているとします。
注文キャンセル後に出荷登録を取り消せるのか
同じ注文を再送した場合に二重登録されないか
エラー発生後に安全に再送できるのか
配送状況取得APIには呼び出し回数の制限があるのか
配送完了をWebhook等で通知してもらえるのか
こうした不明点を一括して「API仕様未確定」と扱うと、案件全体が止まりやすくなります。
そこで技術側で、
正常に登録できる条件を確認する
キャンセルや再送など条件を変えて試す
リクエスト内容と結果を記録する
仕様書の該当記述と照合する
自分たちでは判断できない部分を切り出す
再現条件と実際の結果を添えてAPI提供元へ問い合わせる
ところまで進めます。
たとえば、
通常の出荷登録は問題なく成功するが、同一注文IDで再送するとこのレスポンスになる。仕様書上は重複登録時の扱いが明記されていない。既存登録を返す仕様なのか、エラーとして扱う仕様なのか。
という状態まで整理できれば、サポート側にも確認したいポイントが伝わりやすくなります。
回答を待っている間も、確定済みのデータマッピングや通常登録部分について設計を進められる場合があります。
外部APIの不明点を一つの巨大な「仕様未確定」として扱わず、検証可能な単位へ細かく分解することがポイントです。
調査しても、すべてを事前に確認できるとは限らない
一方で、調査工程を設ければ必ずすべての仕様を確定できるわけではありません。
外部サービスによっては、
本番環境でしか再現できない状態がある
テスト環境と本番環境で利用できる機能が異なる
決済の与信・売上確定など、本番に近い条件でなければ確認しづらい
外部サービス側の状態遷移を自由に再現できない
レート制限や大量データ処理など、通常のテストでは確認しきれない
といったケースがあります。
この場合、調査工程の目的は「すべてを解決すること」ではありません。
どこまで確認できて、どこから先は本番またはAPI提供元の回答がなければ判断できないのかを明確にすることです。
場合によっては、
この条件が確認できるまで実装開始しない
確定済み部分だけ先行する
未確認部分は前提条件として残す
リリース後に確認する運用を設計する
という判断になります。
調査の結果、現時点では実装を始めない方がよいと分かることもあります。
それも、手戻りを防ぐための重要な調査成果です。
調査工程の成果物は「分かったこと」だけではない
API調査を行った結果、すべての疑問が解決するとは限りません。
それでも、
確認できた仕様
実際に検証した内容と結果
顧客システムとのデータ対応
API提供元へ問い合わせ中の事項
顧客側で判断が必要な事項
実装できる範囲
現時点では実装できない範囲
実装へ進むための前提条件
が整理されていれば、次の判断ができます。
特に重要なのは、何がまだ分からないのかを明確にすることです。
外部APIの仕様が不十分な案件では、この整理そのものが調査工程の成果物になります。
外注先へ相談するときは「整理済み資料」を作り込まなくてもよい
API仕様が不明確な案件を外部のバックエンド開発会社へ相談するとき、発注側で完璧な資料を作る必要はありません。
まず渡せるものをそのまま共有します。
たとえば、
連携対象の外部サービス
現在入手しているAPI仕様書や開発者ドキュメント
顧客案件で実現したいこと
顧客システムの概要
テスト環境・アカウントの有無
すでに試したことと、その結果
現時点で困っている点
API提供元への問い合わせ状況
希望するリリース時期
です。
特に有用なのは、すでに試したことと、その結果です。
「仕様が分かりません」という情報だけよりも、
ここまでは試した
この条件では動いた
この条件では期待と違った
この部分だけ判断できていない
という情報があれば、調査の開始地点を大きく前へ進められます。
まとめ：API仕様が曖昧な案件ほど、調査力を含めて外注する
外部APIの仕様が不明確だからといって、バックエンド部分を外注できないわけではありません。
重要なのは、
仕様書だけで判断しない
テスト環境で実際に挙動を確認する
顧客システムとのデータ対応を整理する
非同期処理まで含めて連携全体を見る
不明点を細かく切り分ける
API提供元へ具体的な条件を示して問い合わせる
調査結果をもとに実装範囲を確定する
という進め方です。
そして、調査した結果は見積OK・条件付き・調査先行・保留のいずれかとして整理します。調査すれば必ず実装へ進めるわけではなく、確認できない条件が重要であれば、実装を待つ判断も必要です。
外部API連携では、実装技術だけでなく、分からない仕様を一つずつ検証し、問題を切り分け、第三者とのやり取りを通じて仕様を確定していく力が求められます。
プレイリーソリューションズでは、Java / AWSを中心としたバックエンド開発、外部API連携、決済連携などに対応しています。
SIer・Web開発会社・DX支援会社の方で、「顧客案件のAPI連携だけ不確定要素が大きい」「API提供元への確認も含め、技術調査から任せたい」という場合には、調査・整理工程を先行させ、その後に成果物単位の設計・実装へ移る進め方も可能です。
