API設計の案件を探すと、要件定義や実装とセットになった募集ばかりが目に入ります。設計だけを任される案件は、決め方が1つに揃っていない場所に生まれます。複数のチームやベンダーが関わる開発では、命名規則やバージョンの付け方が現場ごとに異なり、後から解釈の違いが表面化しがちです。この記事では、合意すべき領域をどの順番で文書に残せばよいかを、公的なガイドブックの記述に沿って整理します。

1. API設計の案件で問われるのは、決め方が決まっていない場所で決めることです

設計だけを任される案件が生まれる理由

APIによるデータの提供事例は増えつつあるものの、その設計・運用は各府省の個々の指針によって行われているのが現状です¹。この状況を受けて、技術的に考慮すべき事項や留意点をまとめたガイドブックが整備されています。組織をまたいでAPIを使う場面では、同じ課題が繰り返し起きます。呼び出す側と提供する側が別の組織に属していると、命名や表記の基準を最初にそろえておかなければ、後から仕様の解釈がずれてしまいます。

ある技術を選べるかどうかだけでなく、関係者ごとに前提が異なる状況で、どの順番で合意を取り付ければ手戻りが少ないかを見立てられるかが問われます。決め方が揃っていない現場で合意を形にしてきた経験は、面談で伝えられる材料になります。プロジェクトの途中から加わるケースでは、既存の実装を壊さずに、決め方をどこまで遡って直せるかという判断も欠かせません。

このガイドブックは2024年9月30日に改定され、同期・非同期API設計の考え方やAPIゲートウェイの活用、省庁間データ交換のための標準規格、モニタリングとロギング、SLAとSLOの設定、API提供の告知などが新たに書き加えられました⁷。整備からしばらく経った分野ではなく、今まさに更新が続いている領域だと分かります。改定のたびに参照する版がずれると、関係者の間で前提がかみ合わなくなるため、案件に加わる際にはどの版を基準にしているかを確認しておく必要があります。

「後から仕様が変わった」を避けるために

案件が始まってから「思っていたものと違う」という行き違いが起きると、手戻りの範囲は実装量に比例して大きくなります。原因は技術的な難しさよりも、決めるべき項目を先送りにしたまま実装を進めてしまうことにある場合が目立ちます。次の章で扱う5つの領域は、こうした行き違いが起きやすい箇所を先回りして示したものです。順番に確認し、文書として残しておくことが、行き違いを避ける近道になります。

設計だけを任される案件は、要件定義や実装を含む案件と比べると数は限られます。それでも、複数チームやベンダーが関わるプロジェクトでは、実装より前に合意を形にする工程が独立した仕事として切り出されることがあります。会議の調整だけを担当するわけではなく、決めた内容を文書として残し、後から参照できる形にすることも役割に含まれます。次の章では、合意すべき領域を5つに分けて見ていきます。

2. 合意する領域は5つに分けられます

技術選定より先に固める5つの領域

ガイドブックに書かれている取り決めを、この記事では命名規則・バージョン・エラー・認証・SLAの5つの領域に分けて見ていきます。技術選定そのものより、この5つを誰がどの順番で固めるかが、案件の進めやすさを左右します。

出典：デジタル庁「APIテクニカルガイドブック」（2024年9月改定）をもとに作成

5つの領域を後回しにすると起きること

命名規則は呼び出す側が参照する言葉の基準、バージョンは仕様変更の影響範囲を区切る仕組み、エラーは失敗したときの伝え方、認証は誰がどこまで扱えるかを確認する仕組み、SLAは提供する品質の基準です。実装より前にこの5つを固めておかないと、あとから解釈の違いが表面化し、手直しの範囲が広がりやすくなります。次の表は、領域ごとに先に決めておく内容と、決めないまま進んだ場合に起きやすいことをまとめたものです。

領域	先に決めておく内容	決めないまま進んだ場合に起きやすいこと
命名規則	リソース名は複数形にし、キャメルケースではなくスネイクケースで表記する2	エンドポイント名の解釈がチームごとに割れ、呼び出す側の実装がそろわなくなります
バージョン	メジャーバージョンをURIに含め、「v」と整数で表す3	互換性が崩れる境目が分からなくなり、切り替えのたびに影響範囲を洗い直すことになります
エラー	標準API仕様として、リソース命名規則・HTTPメソッドの使用と並んでエラーハンドリングの標準的な仕様を定義するとされています4	失敗時の伝え方が呼び出す側ごとに異なり、原因の切り分けに時間がかかります
認証	標準的な認証・認可プロトコルを用いる5	チームごとに異なる仕組みを持ち込み、後からの統合が難しくなります
SLA	性能、可用性、サポートレベルの基準を定める6	提供する品質の水準について、認識の違いが後から表面化します

領域ごとに確認する相手が変わります

命名規則やバージョンは実装チームの内部で完結しやすい一方、認証やSLAは複数の組織にまたがる約束になりやすく、確認や了承を得るまでに時間がかかります。どの領域を誰に確認すればよいかを見立てることも、設計を担当する側の役割に含まれます。着手の早い段階で、確認が必要な領域を洗い出しておくと、後半になって承認待ちで進行が止まる事態を避けやすくなります。この表からも分かるとおり、エラーの扱いのように資料の記載が限られる領域は、案件ごとに個別の確認が必要になります。

3. 命名とバージョンは、後から変えにくい取り決めです

リソース名の表記をそろえる

ガイドブックは、リソース名を複数形にし、キャメルケースではなくスネイクケース（単語間をアンダースコアで繋げる表記法）で表記することを推奨しています²。抽象的な名詞は避け、利用する側がリソースの中身を判断できる単語を選ぶことも合わせて示されています。このガイドブックが推奨している書き方であって、唯一の正解として押し付けられているわけではありません。それでも、複数の開発者が同時に手を動かす案件では、参照できる基準が公開されているかどうかが、合意の速さを左右します。基準が公開されていると、新しく案件に加わったメンバーも、既存のエンドポイントの意図を推測せずに理解できます。

バージョンの表記と、その先の運用

バージョンについては、メジャーバージョンをURIに含め、「v」に整数を続けて表し、小数にしないことが示されています³。これはURIの表記に関する取り決めで、バージョン管理の考え方そのものについては、セマンティックバージョニングの原則を取り入れることも合わせて推奨されています³。URIの見え方と、開発側の管理方法は別の話として扱われている点に注意が必要です。バージョンの切り方が明確であれば、古い版を使い続けている呼び出し側への影響も、事前に把握しやすくなります。反対に切り分けが曖昧だと、どこまで互換性を保証しているかの確認だけで時間を要します。

出典：デジタル庁「APIテクニカルガイドブック」（2024年9月改定）をもとに作成

版を重ねるときに確認しておきたいこと

ガイドブック自体も2024年9月30日に改定されており⁷、参照する基準は固定されたものではなく更新され続けています。案件に加わる際には、どの版を前提に取り決めが行われているかを確認しておくと、後から「参照していた基準が古かった」という行き違いを避けやすくなります。バージョンの取り決めは、APIそのものだけでなく、参照する資料の扱い方にも当てはまる考え方です。URIの形と資料の版、どちらか一方だけを確認しても、後になって食い違いに気づく展開になりがちです。両方をあわせて確認しておくことが、この案件で求められる仕事です。

4. 項目の意味をそろえる層があります

共通データモデルという考え方

省庁間でデータを交換するためのAPI標準規格は、政府相互運用性フレームワーク（GIF）の一部として位置づけられています⁴。この標準規格では、人物、組織、住所、日時といった基本的なデータ項目について共通のデータモデルを定義することで、異なる組織の間でもデータの解釈がそろうようにしています⁴。命名規則やバージョンが表記の取り決めだとすると、共通データモデルは項目の意味そのものをそろえる層にあたります。

共通データモデルが扱う代表的な項目

同じ「氏名」という項目でも、姓と名を分けて持つか、続けて1つの文字列として持つかが組織によって異なれば、連携のたびに変換の手間が発生します。住所や日時の形式がそろっていない場合も同様で、比較や検索のたびに読み替えが必要になります。次の表は、共通データモデルが扱う代表的な項目と、そろえる狙いを整理したものです。

項目	そろえる狙い
人物	氏名や属性の持ち方を統一し、組織をまたいだ照合を可能にします
組織	組織名や所属の表し方をそろえ、参照先を一意に特定できるようにします
住所	住所の区切り方や表記をそろえ、変換の手間を減らします
日時	日時の形式をそろえ、順序や有効期限の比較を正しく行えるようにします

設計を担当する側が確認する作業

設計を担当する立場では、共通データモデルに沿っているかどうかを確認する作業も仕事に含まれます。個々のAPI定義書だけでなく、複数のAPIをまたいでデータ項目の一覧を見比べ、表記のずれがないかを確認する工程です。地道な作業に見えますが、連携が始まってからの手戻りを防ぐ意味を持ちます。項目の意味がそろっていても、それを扱う側の認証の仕組みが組織ごとに異なっていれば、連携の安全性は保てません。次の章では認証の合わせ方を見ていきます。

5. 認証方式は各チームで別々に決めない

標準的なプロトコルに寄せる理由

省庁間データ交換の標準規格は、セキュリティ要件として標準的な認証・認可プロトコルの使用を規定しています⁵。これにより、データを交換する際の安全性を確保する狙いです。認証プロトコルの例としてOpenID Connectが挙げられていますが⁵、これはあくまで例であり、唯一の選択肢として示されているわけではありません。

各チームが別々に決めることの影響

複数のチームやベンダーが関わる開発では、認証の仕組みをそれぞれの都合で決めてしまう場面があります。あとから1つの窓口に統合しようとすると、対応表を作る手間や、想定していなかった権限の抜けが生まれやすくなります。標準的なプロトコルに揃えておくことは、技術選定というより、複数の関係者の間で交わす約束に近い判断です。

出典：デジタル庁「APIテクニカルガイドブック」（2024年9月改定）をもとに作成

提案するときに確認しておきたいこと

認証の方式を提案する際は、案件ごとに指定された基準があるかどうかをまず確認し、指定がなければこうした公開資料を参考に提案を組み立てる進め方になります。後から仕組みをそろえ直すよりも、着手時点で標準的なプロトコルに合わせておくほうが、修正の範囲は小さく済みます。

6. 「動くか」ではなく「どの水準で出すか」を決めます

SLAが扱う3つの基準

サービスレベル合意（SLA）では、省庁間でのAPI利用に関する性能、可用性、サポートレベルなどの基準を定めます⁶。動作するかどうかの確認だけでなく、どの水準で提供し続けるかを、あらかじめ文書にしておく考え方です。

SLAで整理しておきたい3つの基準

性能はどのくらいの速さで応答するか、可用性はどのくらいの時間利用できる状態を保つか、サポートレベルは問い合わせにどこまで対応するかという基準です。具体的な数値目標はガイドブックには示されていないため、案件ごとにクライアントと協議して定める項目になります。次の表は、この3つの基準と確認しておきたい観点をまとめたものです。

基準	確認しておきたい観点
性能	応答にかかる時間について、どの水準を目安にするか
可用性	利用できる状態をどの程度保つか。具体的な数値目標は案件ごとにクライアントと協議して定めます
サポートレベル	問い合わせや障害対応に、どこまでの範囲で応じるか

出典：デジタル庁「APIテクニカルガイドブック」（2024年9月改定）をもとに作成

設計を担当する側の役割

設計を担当する側は、SLAの数値そのものを決める立場になるとは限りませんが、性能・可用性・サポートレベルという3つの観点を整理し、クライアントとの協議のたたき台を用意する役割を担うことがあります。3つの基準をあらかじめ整理しておくと、契約や協議の場で何を確認すればよいかが明確になり、後から「聞いていない」という行き違いを防ぎやすくなります。

命名規則からSLAまで、5つの領域を順に固めていくと、複数の関係者が関わる案件でも合意の抜けが減っていきます。最後によくある質問にまとめます。

7. よくある質問

API設計だけを任される案件は実際にありますか

要件定義や実装まで一括して担う案件と比べると数は限られますが、複数チームやベンダーが関わる開発では、実装より前に合意を形にする工程が独立した仕事として切り出される場面があります。API設計の経験を積み上げてきた場合、こうした案件の存在を知っておくことが選択肢を広げます。

命名規則やバージョンの取り決めは誰が最終的に決めますか

関係する組織やチームの間で協議して決める性質のものです。デジタル庁のガイドブックのように、参照できる公開された基準がある場合は、それを土台にして議論を進めやすくなります。民間企業の案件でも、同じ考え方が参考になる場面はありますが、この資料自体は政府情報システムを対象にしたものです。

認証方式はOpenID Connect以外の選択肢もありますか

ガイドブックが挙げているのは例としてのOpenID Connectであり、唯一の選択肢として指定されているわけではありません⁵。重要なのは特定のプロトコル名よりも、各チームが別々に決めず、標準的な仕組みに寄せるという合意そのものです。

SLAの数値目標はどうやって決めればよいですか

ガイドブックには性能、可用性、サポートレベルという基準の枠組みは示されていますが⁶、具体的な数値目標は記載されていません。案件ごとにクライアントと協議しながら、実態に合わせて定めていく項目です。

複数チームとの調整がある案件は、リモートでも進められますか

取り決めを文書で残す進め方は、対面よりもむしろ記録が残る形と相性がよい面があります。Remoguが扱う案件は、90%以上がフルリモート可能です⁸。打ち合わせの頻度や、設計レビューをどの単位で行うかは案件によって異なるため、募集内容で稼働の条件を確認してみましょう。

この記事で扱う内容は民間企業の案件にもそのまま使えますか

紹介した資料は政府情報システムを対象にしたものです。命名規則を公開しておく、標準的なプロトコルに寄せるといった考え方は、同じ考え方が参考になる場面もありますが、民間企業の案件がそのまま同じ基準に従っているとは限りません。案件ごとに、参照すべき基準があるかどうかをまず確認することが出発点になります。

5つの領域を順に確認しておくと、複数の関係者が関わる案件でも、後から仕様の解釈がずれる場面を減らせます。次にAPI設計の案件を検討するときは、技術選定よりも先に、何をどの順番で文書に残すかを確認してみましょう。

※公開中の案件数は時期によって変わります。記事中の案件の傾向は執筆時点のものです。

出典・参考情報

＊1 デジタル庁「APIテクニカルガイドブック」DS-464-2（2024年9月）
＊2 デジタル庁「APIテクニカルガイドブック」DS-464-2（2024年9月）
＊3 デジタル庁「APIテクニカルガイドブック」DS-464-2（2024年9月）
＊4 デジタル庁「APIテクニカルガイドブック」DS-464-2（2024年9月）
＊5 デジタル庁「APIテクニカルガイドブック」DS-464-2（2024年9月）
＊6 デジタル庁「APIテクニカルガイドブック」DS-464-2（2024年9月）
＊7 デジタル庁「APIテクニカルガイドブック」DS-464-2（2024年9月）
＊8 Remoguサイト公開情報（案件の90%以上がフルリモート可能）