社内APIの仕様は何を決める？必須IDの意味と応答を確かめる方法

API仕様は、情報の形と業務上の意味をつなぐ説明

この記事の社内APIは、社内アプリから別の仕組みに決めた形式で問い合わせ、返答を受ける窓口を想定しています。仕様では「何の操作か」「どこへどう渡すか」「どの情報を渡すか」「何が返るか」を説明します。

操作

請求一件の状況を確認する、など、呼び出して行いたい仕事です。実際の接続先URLやHTTPメソッドは、そのAPIの仕様で確かめます。

リクエスト

APIへ渡す依頼です。問い合わせる請求番号など、操作に必要な情報を含みます。

JSON

項目名と値を対応させて表す形式です。この例の caseId と elementSystemID は項目名で、そこへ入る文字列が値です。項目の英語名だけでは、社内で何を指すかを決められません。

レスポンス

依頼に対する返答です。通信の結果を示す情報と、返された本文を、そのAPIの決まりに沿って読みます。

Swaggerとして渡された画面に操作名や入出力の形があっても、業務上の番号の定義や、今の利用者が使ってよい値まで説明されているとは限りません。「文字列を入れる」と分かることと、「どのシステムの何の番号を入れるか」と分かることを区別しましょう。

OpenAPI仕様3.2.1は、操作、送る本文、応答、入出力の型などを記述する枠組みを定めています。本稿はその説明範囲を参考にします。架空のAPIが同じ版を採用している、仕様の記述どおりに実装・運用されているという証拠にはしません。

一件の請求で、何を問い合わせ何に使うかを決める

「APIをつなぎたい」から始めると、読める項目を全部送る、返る情報を全部使うという話になりがちです。まず業務担当が、一件の問い合わせを選び、返答を受けた後に何を確かめたいかを説明します。IT発注担当は、その仕事と、呼び出す操作・必要な情報・返答の読み方を結び付けます。

1. 業務の問いを一文にする。どの請求の何を確認し、返答を誰のどの判断に使うかをそろえます。操作名が似ていても、確認と更新は同じ仕事として扱いません。
2. 操作と仕様の版をそろえる。受け側の担当へ、対象の操作、接続先、メソッド、利用する版を確かめます。別環境や古い仕様の例を、そのまま今回の条件に混ぜないためです。
3. 入力と返答を一組で読む。請求番号と必須IDを何から取り、その入力に対して何が返れば、最初の業務の問いに答えられるかを説明します。返答に必要な情報が足りなければ、呼ぶ操作や業務の使い方を見直します。

値そのものの意味・正本・更新担当を広く整理する場合は、新システムのデータ項目と元情報を決める方法を参照できます。本稿では、APIの一操作として送る値と受け取る返答の取り決めへ進めます。

必須IDは、何の番号か・どこから取るか・何を許すかを分ける

仕様書で見える架空のJSON例は次の形です。SYS-A は説明用文字列で、正式に使える値とは確認されていません。この表示を、送信してよいリクエストの完成例として使わないでください。

{
  "caseId": "C101",
  "elementSystemID": "SYS-A"
}

caseId はこの例の請求番号に対応します。一方、elementSystemID は名前にIDとあっても、その対象を決められません。システム名の略に見えること、他のログに同じ文字列があることだけでは、今回の請求で使う根拠にならないためです。

同じ「システムの番号」でも、指すものが違えば取り方が変わる

仮に「呼び出すアプリを識別する番号」と回答されたなら、そのアプリを管理する担当から、利用者や環境に対応する正式な割当値を確かめます。「請求の元記録を管理するシステムの番号」と回答されたなら、請求の管理元をたどり、その記録との対応で値を選ぶ必要があります。これは回答別の考え方で、この例のIDの意味がどちらかへ決定したものではありません。

IT発注担当は、値の意味、元情報、割当・変更する担当、許す値の範囲、使える環境を一緒に記します。値の一覧がある場合も、今回の版・環境で有効なものかを確かめます。自由に付けてよい番号なのか、登録済みの値だけを使うのかで、呼び出し側の実装と確認が変わります。

「必須」は、値の意味や受理の保証を表さない

この架空記録の required=true は、仕様書で必須と記されていることを残した説明用の値です。実際のOpenAPIファイルの設定例ではありません。OpenAPIの requestBody.required は本文全体が必要かを表し、JSON Schemaの required は必要な項目名の一覧です。実際の版と、どの場所に必須性が書かれているかを開発担当が確認します。

JSON Schemaの必須項目の解説でも、項目がないことと、値が null であることは別とされています。空文字 "" や、型として文字列であることも、業務上使える値かどうかとは別です。省略・null・空文字・許容外の値を受けたときに、APIが何を返し、呼び出し側がどう扱うかを決めます。

例・ログ・コードは、意味の確認に使う手掛かり

既存の例やログから、実際に使われた項目の形を調べることはできます。ただし、その値がどの環境・利用者・業務条件のものかを確かめ、項目を定義する人と受け側の担当へ照合します。コードを読んで候補が見つかっても、その候補の使用権限や現在の許容値まで決まったとは扱いません。

成功と既知の失敗で、返答と次の処理を決める

入力をそろえるだけでは、呼び出した後の業務を作れません。受け側の担当と「何を受け付け、どういう条件なら何を返すか」を決め、呼び出し側は返答を受けた後の表示・保留・問い合わせを対応させます。この例の実応答は未観測なので、以下は合意する観点です。

状況を確認できた場合

返答がどの請求に対応するか、業務で必要な状況をどの欄から読むか、情報の時点をどう扱うかを確かめます。通信が完了しただけで、必要な業務情報が得られたとは判定しません。

必須IDがない・値を受け付けられない場合

どの返答で区別でき、利用者へ何を知らせ、誰が元の値を確認するかを決めます。無関係な例示値を埋めて通す処理や、原因を確かめない同じ依頼の繰返しにしません。

その権限では確認できない場合

利用できる操作・対象の範囲と、権限を確認する担当を対応させます。別の利用者の情報へ置き換えるのでなく、正しい利用条件を確認します。

対象が見つからない、返事が来ない場合

対象なしを何で示すかと、返答未着をどう扱うかを分けます。再送してよい条件、受け側へ状況を聞く方法、保留の表示を確かめます。返事がないことだけで、受け側が何も行っていないとは推定しません。

OpenAPIのResponses Objectは、期待する成功と既知のエラーを説明する範囲を示します。全ての応答を事前に網羅できるという保証ではありません。HTTPのステータスコードと返答本文のどの情報で何を判断するかは、対象APIの仕様で具体化します。他のサービスのコードやエラー番号を、この架空例の返答へ流用しません。

APIから得た情報を人向けの帳票へ表示する場合は、さらに誰が何を見るかを整理します。帳票の使い方と要件を決める方法はその段階の参考で、APIの受理条件や返答そのものとは区別します。

送り手・受け手・業務責任者で、答える範囲を合わせる

担当開発者へ「このAPIを教えてください」と一度に尋ねるより、一件の仕事と、分からない項目を指して質問すると、答えが仕様へつながります。担当が忙しくても、今分かる内容と答えを確認する人を分けて進められます。以下の役は相談する範囲で、実際の個人名や担当配置が決まった記録ではありません。

• 業務の意味を決める人：請求番号が指す記録、確認したい状況、返答を使う判断を説明します。IDの意味を業務として確定できる人も確かめます。
• 呼び出すアプリの担当：各値を何から取得するか、必須の値を用意できないときの保留・表示・修正の方法を説明します。
• APIを提供する担当：操作と版、入力の意味と許容条件、期待する返答、権限、試験環境・試験用値の扱いを説明します。別の管理担当が決めるものは、その確認先につなぎます。

請求一件の状況を確認するため、この操作を使いたいです。例には caseId と elementSystemID があります。後者は何の番号で、どの元情報から取り、誰が割り当てる値でしょうか。例の SYS-A は説明用として扱い、今は許容値と確定しません。

値がそろった場合、欠ける・許容外の場合、確認する権限がない場合の返答と、呼び出し側の次の処理を合わせたいです。対象の版、使える試験環境・権限・試験用値、答えを確認する担当を教えてください。回答に応じて入力例と期待する応答を直し、一件で照合します。

受け側と業務側で説明が違うときは、呼び出し側だけで都合のよい意味を選びません。違いが値の名前、管理元、適用する版・環境、業務の使い方のどこにあるかを分け、同じ入力例と返答の読み方へそろえます。

図で、一件の請求・送る例・受け側の返答を対応させる

解説図を原寸で見る

図から決める次の作業：意味が分からないIDを指し、何の情報か・どこから取るか・どの値を許すかを担当者へ確かめます。入力と返答を同じ操作の仕様へ結び、回答に応じて例を直してから、利用できる環境と値で照合します。

回答で仕様例を直し、期待と実際の結果を確かめる

IDの意味と管理元が分かったら、値の選び方を直す

番号の対象、正式な値の取得元、割当・変更する担当を、入力項目の説明へ結びます。固定の割当値ならどの環境・利用者に対応する値かを、請求ごとに選ぶ値ならその請求の元記録との対応を説明します。例示値を実際の試験用値へ替える場合も、今回の条件に使えることを確認し、元の例と混ぜません。

必須の値を用意できないと分かったら、保留か仕様変更を選ぶ

現在の操作がその値を必要とするなら、呼び出し前に用意できない状態をどう知らせ、誰が補うかを決めます。業務上は不要だと分かった場合は、受け側と仕様・実装を変更する必要があるかを検討します。呼び出し側だけで必須項目を消し、相手も受理すると想定する変更にはしません。

返答が業務の問いに足りないなら、操作や使い方を見直す

請求の状況を判断するための情報が返らないなら、別の操作が必要か、返す内容を変更できるか、業務として何を保留するかを確かめます。入力が通ったことだけで完了せず、最初に決めた問いへ答えられるかで判断します。

利用できる試験条件がそろったら、一件で照合する

1. 同じ条件をそろえる。操作・版・環境、使える権限と架空の試験用値、期待する返答と業務上の判断を確認します。実顧客の値を本文の例に持ち込む必要はありません。
2. 入力と期待する結果を先に対応させる。必要な値がそろう場合と、欠損・許容外・権限が合わないなど必要な失敗条件を分けます。各条件で何を返し、呼び出し側が何をする予定かを説明します。
3. 許可された範囲で試し、実結果を分けて記録する。返答のコードと本文、対象の請求との対応、次の表示・保留などを予定と比べます。この架空例では実送信・実結果の取得は行っていません。
4. 違いの場所へ戻る。入力の形が違うなら作り方へ、値の対象が違うなら定義と取得元へ、版や環境が違うなら試験条件へ戻ります。相手の実装と仕様が異なる場合は、提供側へ同じ条件を示して照合します。

確認を終える目安は、一つの入力について、なぜその値を選び、何が返れば業務の問いに答えられ、例外ならどこへ戻るかを説明できることです。仕様の読み合わせ、実装、試験で得た結果を、それぞれ分けて残します。記事に確認観点を書いたことを、動作試験の合格へ置き換えません。

請求などの記録をどう分けてIDで結ぶかが先に曖昧な場合は、業務の記録の単位と関係を設計する方法も参照できます。記録同士の関係と、APIの一操作の入出力を区別して整理しましょう。

JSONの例があっても、送信してよい仕様とは限らない

請求C101にはIDとJSONの説明用例があり、別の請求C102はその情報が未取得です。ただし、どちらもIDの意味や使ってよい値、応答は未確認です。例を写せることと、実際に送信できることを分けて読みます。請求番号は、仕様と送信例の対応を示すための架空の番号です。二つは別の検討記録で、修正前後や実送信の結果ではありません。

{
  "caseId": "C101",
  "elementSystemID": "SYS-A"
}

次にすること：二つの例のどちらでも、APIの管理担当へ未確認事項を聞き、仕様と送信例を一緒に更新します。例が未確認の部分を推測で埋めたり、例があるだけで本番への送信を進めたりしないでください。

まとめ：必須IDの意味と、入力に対応する返答をそろえる

社内APIの仕様では、一つの業務操作を選び、送る項目の意味・元情報・使ってよい値・決める担当と、受け側の返答を結びます。JSONの形や必須の印が分かっても、業務上どの値を使い、何を判断するかは別に確認が必要です。

回答が来たら、値の選び方、欠損時の保留、操作の使い方、期待する返答を直します。利用できる試験環境・権限・値がそろってから、入力と実結果を同じ条件で照合し、違いを定義・取得元・作り方・試験条件へ戻して確かめます。

最初の一歩は、一件の業務目的と、意味が分からない一項目を示し、「何の番号で、どこから取り、誰が値を決めるか」を受け側と業務側へ尋ねることです。その答えを、具体的な入力例と返答の読み方へ反映してください。