LASSIC Media らしくメディア

監修・編集責任者：牛尾 昭昌（株式会社LASSIC 執行役員）

連携用のAPIを業務委託エンジニアに作ってもらったら、項目名の書き方も日付の形式も、社内の別のAPIと違っていた。エラーが返ってきても、呼び出した側では何が悪かったのか分からない——。システム連携を社外のエンジニアと進める現場では、こうした食い違いが起こりがちです。システム連携のAPI設計・開発とは、システムどうしがデータをやり取りするための仕組みであるAPIについて、データを求めるときの書き方と、返すデータの形を決め、実際に作ることを指します。

決まりを作るときの土台として使えるのが、デジタル庁の「APIテクニカルガイドブック」です。政府機関がAPIを作るときに技術的に考えておく点をまとめた資料で、民間のシステムにも参考になる内容が並んでいます。ただし万能ではなく、政府機関向けに書かれた資料なので、どこまで取り入れるかは頼む側が決める必要があります。本記事では、業務委託エンジニアにAPI設計・開発を頼むマネージャーに向けて、決まりを先に渡す理由、呼び出し方・返し方・セキュリティと運用で決めること、受け取る文書、そして外部に委託するときに確認したい点を整理します。

システム連携のAPI設計・開発とは

APIテクニカルガイドブックは、APIの開発・運用を担当する職員を「各府省担当者」、その職員から受託して開発・運用を行う民間事業者などを「API構築担当者」と呼んでいます。^*1 企業では、開発を頼む社内のマネージャーが前者に、業務委託エンジニアが後者に当たります。

ガイドブックは、API構築担当者に向けて具体的な取り組みを示す一方で、各府省担当者にも目を通して作業の概要をつかむよう勧めています。そうすれば「作業管理や担当者とのコミュニケーションに役立つ」としています。^*1 頼む側が作業の概要を知らないまま任せると、できあがったAPIが社内の決まりに合っているかを確かめられません。

API設計・開発で決めることは、大きく分けると次の4つです。

• 呼び出し方（URIと呼ぶ呼び出し先の文字列、操作の種類、渡す値）
• 返し方（データの形式、項目の書き方、エラーの伝え方）
• セキュリティと運用（認証、利用の制限、処理が失敗したときのデータのずれ、サービスの水準）
• 受け取る文書とテストの環境

なぜ決まりを先に渡すのか

理由の一つは、あとから直すと影響が大きいことです。ガイドブックは、運用を始めたあとは、どのAPIにも共通するURIの先頭の部分（ベースURI）を基本的に変えないこととし、変える場合は、そのAPIを使うシステムの開発者に前もって知らせるよう求めています。仕様を変えるときも、呼び出す側の改修に時間がかかることがあるため、通知から実施まで十分な移行期間をとるよう書いています。つながるシステムが増えてからでは、項目名や形式をそろえ直す手間が大きくなります。

もう一つは、資料によって勧める書き方が違うことです。ガイドブックは、URIで単語を区切るときにスネイクケース（単語をアンダースコアでつなぐ書き方）を勧めています。一方、IPA（情報処理推進機構）の「API標準設計ガイド・基礎編」は、URIの単語の区切りにハイフンを使うとしています。^*2 どちらでも動くAPIは作れますが、業務委託エンジニアがそれぞれ慣れた書き方で作ると、担当者が替わるたびに書き方も変わります。社内でどちらかに決め、最初に渡しておくことになります。

IPAのガイドは、APIの設計書の書き方が標準化されていないと、書式や書く細かさがそろわず、読み解くのに手間がかかると指摘しています。^*2 決まりといっても長い規程は要らず、次の節からの表のように、項目と選んだ書き方を並べた一覧があれば依頼の資料に使えます。

呼び出し方で決めること

呼び出し方について、ガイドブックはREST（Webの仕組みに沿ったAPIの設計の型）に基づく設計を勧め、URIや渡す値の決め方を具体的に挙げています。頼む前に決めておきたい主なものを表にまとめると、次のようになります。

もう一つ決めておきたいのが、同期と非同期の使い分けです。ガイドブックは、処理時間が短い場合（目安は1秒未満）は、結果が返るまで呼び出した側が待つ同期APIを使うとしています。1秒以上かかる処理には、受け付けたことだけを先に返し、結果は後で取りに行く非同期APIを使います。^*1 非同期では、受付時にHTTPステータスコード（処理の結果を表す3けたの番号）の202 Accepted（受け付けたが処理は終わっていないという応答）を返し、処理の状況を確かめる先を知らせます。完了したら303 See Other（結果の置き場所へ案内する応答）で結果の場所を示します。

たとえば、取引先から届いた数千件の受注データをまとめて取り込むような処理は、非同期の候補になります。同期で作ると、呼び出した側が結果を待つ間に通信が時間切れで切れるおそれがあります。どの処理を非同期にするかを連携の一覧に書いておくと、業務委託エンジニアとの認識がずれにくくなります。

返し方で決めること

返すデータの形式について、ガイドブックはJSON（キーと値の組でデータを書く形式）を勧めています。XMLに比べてデータ量が少なく、処理の負荷も軽いためです。ただし、すでにXMLやCSVで環境が整っている場合は、扱う情報に応じて選ぶとしています。文字コードはUTF-8を使い、外字（標準の文字コードにない文字）は使わないとしています。

項目の書き方は、国際標準などに合わせることを勧めています。日時はISO 8601に沿って「2017-02-06T13:50:40+0900」のように書き、都道府県はJIS X 0401のコードで、東京都を「13」と表します。^*1 社内の古いシステムが「2017/2/6」のような社内だけの書き方で日付を持っている場合は、どのシステムの側で書き方を変換するかも決めておきます。

エラーの伝え方は、食い違いが起きやすいところです。ガイドブックは、RFC 7807（HTTPのAPIでエラーの詳しい内容を伝える書式の規格）に沿って、status、type、title、detail、instanceの5つの項目を含めることを勧めています。^*1 detailには、API利用者がどこに問題があるかを理解できる説明文を入れます。形式が決まっていないと、同じ入力の誤りでもAPIごとに返ってくる項目が変わり、呼び出す側のプログラムでまとめて扱えません。

HTTPステータスコードも、どれを使うかをそろえておきます。ガイドブックは、リクエストの誤りに400、認証の失敗に401、値の検査で処理できないときに422、短い時間に呼び出しが多すぎるときに429などを挙げています。^*1 番号ごとに呼び出す側の対応（やり直すのか、利用者に知らせるのか）まで書いておくと、両方の開発が進めやすくなります。

セキュリティと運用で決めること

ガイドブックは、APIを設けることは「外部から常時アクセスできる入口を作ること」になると書き、セキュリティ対策の重要さを強調しています。^*1 通信はTLS（通信を暗号化する仕組み）で暗号化し、利用者の認証は少なくともAPIキー（利用者ごとに発行する識別の文字列）以上の水準にします。個人情報を扱う場合などは、OpenID Connect（利用者の本人確認の規格）による認証も勧めています。

利用の制限も、頼む前に決めておきたい点です。ガイドブックは、利用者ごとに1日のアクセス回数やダウンロード件数に上限を設ける例を挙げつつ、制限を厳しくしすぎると使いにくくなるとも書いています。社内のどのシステムから、どのくらいの頻度で呼び出す想定なのかは、頼む側しか持っていない情報です。

呼び出す側と呼び出される側の処理が、どちらも正しく終わったかをそろえる「整合性」の問題もあります。呼び出された側の処理が成功しても、呼び出した側がその後に異常終了すると、互いのデータが合わなくなることがあります。ガイドブックは、APIをまたいだ処理の管理は複雑になりやすいため、場合によっては手作業での対処を許容するような、簡易な設計を目指すよう勧めています。どこまでを自動でそろえ、どこからを人が直すかは、業務の事情を知る頼む側が決めることです。

運用については、SLA（利用者と合意するサービスの水準）と、それを守るための内部の目標であるSLO（サービスの水準の目標）を定めるよう書いています。例として、可用性（使える状態にある時間の割合）99.99%、95パーセンタイルのレスポンスタイム200ミリ秒以内（応答の速いほうから95%の呼び出しが200ミリ秒以内に返ること）が挙がっています。^*1 数値は自社の業務に合わせて決めるものですが、監視する項目（レスポンスタイムやエラー率など）とあわせて開発を頼む時点で伝えておくと、業務委託エンジニアが作る段階から備えられます。

業務委託エンジニアから受け取るもの

作ってもらったAPIを社内で使い続けるには、文書が欠かせません。ガイドブックは、公開を勧める文書として、API概要、API仕様書、利用規約、利用申請、利用事例を挙げています。社内だけで使うAPIでも、API仕様書に含める項目は、そのまま受け取るものの一覧として使えます。

• API機能（扱うデータと操作の内容）
• 利用方法（呼び出し先、文字コード、認証の方式、利用の制限）
• エラーコード
• リクエストとレスポンス（渡す値、データの形式と項目の説明、サンプル）
• 提供するデータの説明（更新日、提供元、更新のタイミングなど）

仕様書を、APIの仕様を決まった形式で書く規格であるOAS（OpenAPI Specification）に沿って書くと、説明の文書や、試しにAPIを呼び出せる画面をツールで自動で作れます。IPAのガイドは、仕様書をYAML（字下げで構造を表す書式）で書き、書式が標準に沿っているかをツールで検査してから、実際のサーバにつないで動きを確かめる手順を示しています。納品の条件に、書式の検査と実際のサーバでの動作確認を済ませた仕様書を入れておくと、仕様書と実際の動きの食い違いに社内で気づきやすくなります。

テストについて、ガイドブックはAPIモック（完成前のAPIの動きを再現する仕組み）の活用を勧めています。モックがあれば、APIを呼び出す側の開発を、API本体の完成を待たずに並行して進められます。呼び出す側を社内で作るなら、モックを先に用意してもらうことを依頼に書いておくとよいでしょう。OpenAPIでの仕様の書き方は「OpenAPIでAPI仕様設計を外注」で、連携の作業量の数え方は「業務委託エンジニアへのシステム連携の依頼書に書く3つの点」で扱っています。

まとめ：API設計・開発で確かめておきたい3つの点

システム連携のAPI設計・開発を業務委託エンジニアに頼むうえで、確かめておきたい点は3つに整理できます。第一に、名詞の複数形で書くのか、日付をISO 8601で書くのかといった書き方を社内で一つに選び、開発を頼む前に渡すこと。第二に、数千件の受注データの取り込みのように時間のかかる処理や、呼び出す頻度、失敗したときに人が直す部分を、業務を知る頼む側が示すこと。第三に、仕様書を、書式の検査と動作確認を済ませた状態で受け取ることです。この3点を踏まえておけば、「APIごとに項目名や日付の書き方が違い、呼び出す側で毎回変換を書いている」という事態を避けやすくなります。決まりの作り方に迷いがあれば、外部の手を借りるのも一つの選択肢です。

よくある質問

出典

1. *1　参考：デジタル庁「DS-464-2 APIテクニカルガイドブック」（2024年9月30日、PDF）（https://www.digital.go.jp/assets/contents/node/basic_page/field_ref_resources/fe5f0631-c978-42db-8416-6759cfa7e53a/f6ca1b7b/20241001_policies_development_management_outline_04.pdf）。出典：デジタル庁「デジタル社会推進実践ガイドブック DS-464-2 APIテクニカルガイドブック」。1.1 背景と目的（表1-1 関係者の定義）、1.2 適用対象、2.1 URI設計及びリクエスト、2.2 レスポンス（表2-2・表2-7）、2.3 個別データの各パラメータ（表2-9）、2.4 その他（表2-10・整合性担保・APIゲートウェイ）、3 API運用時の留意事項、4 API開発の進め方（表4-2・4.4）を参照（2026年9月確認）
2. *2　参考：IPA「API標準設計ガイド・基礎編」（2025年3月26日、PDF）（https://www.ipa.go.jp/digital/data/jod03a000000a82y-att/api_standard_design_guide.pdf）。出典：独立行政法人情報処理推進機構「API標準設計ガイド・基礎編（付録：サイト利用規約テンプレート）」。1.1 API普及に関する課題、1.4 API標準設計書の作成事例（設計準備・テスト・接続テスト）、2.2 Serversの定義（URIの設計ルール）を参照（2026年9月確認）

Tweet