お世話になっております！新入社員の道守みちるです！
「APIで連携できますので、大丈夫です」。この一言を聞いて、わたしは安心してメモを取りました。でも、席に戻ってから気づいたんです。何が大丈夫なのか、何も確認していない。
「つながる」という言葉は優しいので、つい分かった気になります。ちゃんと確かめるには、何を聞けばいいのでしょう。
「APIで連携できます」と言われたとき、発注する側は何を確認すればいいんでしょうか。
この記事で扱うのは、だいたいこの3つです。📝
- APIとは何で、何をしているものなのか
- 「つながる」と言われたときに、確認したい3つ
- 確認しても、結局分からないこと
APIは「受付窓口」だと思うと、しっくりきました🤔
APIは Application Programming Interface の略です。デジタル庁のガイドブックには、アプリケーション間のデータ共有を可能にする重要な技術であり、これによって異なるシステムが効率的にデータを交換し、機能を共有できるようになる、と説明されていました。
わたしは、役所の受付窓口を想像すると分かりやすくなりました。建物の中に勝手に入って書類棚をあさるのではなく、決まった窓口で、決まった用紙に記入して渡すと、決まった形で返ってくる。あの窓口のAPI版です。
だから大事なのは、「つながるかどうか」よりも「その窓口で何ができるのか」のほうでした。窓口があっても、受け付けてもらえない手続きは受け付けてもらえません。
【Point】「APIがある」は「何でもできる」という意味ではありません。
確認したいことその1：仕様書はありますか
デジタル庁のガイドブックでは、APIを提供する側が公開することを推奨するドキュメントが並べられていました。API概要、API仕様書、利用規約、利用申請の手順、利用事例。仕様書には、扱えるデータや操作、エラーコード、リクエストとレスポンスの形式などを含めるとされています。
つまり、正式なガイドブックが「これを出しましょう」と言っているものがある。だったら、発注する側が「仕様書を見せてください」と言うのは、変な要求ではなさそうです。
もうひとつ、OpenAPI Specification（OAS）という、APIの仕様の書き方を揃えるためのオープンな規格があることも知りました。ガイドブックでも、この規格に沿うことで仕様の共通的な理解が進み、開発作業が効率化されると期待できるとされています。
確認したいことその2：制限はどうなっていますか
ここ、わたしは完全に見落としていました。APIには、使える回数や件数の上限があるのが普通らしいです。
ガイドブックには、使いやすいAPIは攻撃者にとってもアクセスしやすいため、利用者ごとにアクセス回数や取得データの制限をかけることがある、と書かれていました。例として、全件ダウンロードの禁止、1日のダウンロード件数上限、1日のアクセス回数上限などが挙がっています。
これは大事だと思いました。「毎晘10分ごとに全件取ってきて集計したい」と思っても、上限に引っかかれば成立しない。やりたいことと、制限の両方を並べて初めて、できるかどうかが決まります。
認証の話もありました。ガイドブックでは、利用者の認証を強く推奨し、少なくともAPIキー以上の認証レベルを担保することとされています。ただし、APIキーはコピーされてアクセスされる可能性もあるため、強固な対策ではないことに留意する、とも書かれていました。鍵を渡されて安心してはいけないということですね。
確認したいことその3：向こうが変わったとき、どうなりますか
個人的に、これがいちばん大事だと思いました。つないだ相手は、こちらの都合とは関係なく変わります。
ガイドブックの「運用時の留意事項」には、仕様変更などの重要情報は利用しているサービスに影響を与える恐れがあるため、確実に利用者へ通知する必要があると書かれています。さらに、利用者側の改修に時間がかかる場合もあるため、通知から変更実施までに十分な移行期間を考慮する必要があるとも。
あわせて、SLA（サービスの品質に関する合意）と SLO（それを達成するための内部目標）の設定も推奨されていました。含める項目として、可用性、レスポンスタイム、サポート対応時間などが挙がっています。
| 聞くこと | 聞いていないと、あとで困りそうなこと |
|---|---|
| API仕様書はありますか | できると思っていたことが、実は対象外だった |
| 回数や件数の上限は | 流したいデータ量が上限を超えて、頑張っても実現できない |
| 認証はどうやりますか | 鍵の管理責任がどちらにあるのか曖昧なままになる |
| 仕様が変わるときの通知は | ある日突然止まり、原因が分からない |
| 止まったときの基準は | どこまで待てばいいのか、誰も知らない |
なお、確認しても分からないこと
正直に書きます。仕様書を見せてもらっても、わたしには中身が分かりません。英語と記号が並んでいて、ページを閉じたくなります。
ただ、分からなくても聞けることはあると思いました。上の表の5つは、どれも技術の知識がなくても、日本語で答えてもらえる質問です。回答が歯切れ悪いところがあれば、そこがリスクのあるところ、という見当をつける材料にはなります。
【最重要】仕組みを理解するのではなく、「何が決まっていて、何が決まっていないか」を確かめる。発注する側にできるのは、そこまでだと思います。
この「何を決めておくか」という話は、要件定義の記事で書いたことと地続きです。また、連携といっても、フォームで受けて表に流すくらいで済む場面も実際にはあるので、最初からAPIありきで考えなくてもいいのかもしれません。
ここまで書いて思ったこと
【結論】「APIでつながります」は、結論ではなくて、話の入口でした。
ちなみに、ここで参考にしたデジタル庁のガイドブックは、本来は政府情報システム向けのものです。文中にも、地方公共団体や民間の情報システムについては参考としてください、と書かれています。ですので、民間のサービスにそのまま当てはまるとは限りません。そこは注意して読んでいます。
それでも、「提供する側が決めておくべきことの一覧」は、そのまま「使う側が聞くべきことの一覧」になるんだな、というのが、今回の収穫でした。
・・・とはいえ、実際の打ち合わせでこの5つを全部聞けるか、自信はありません。次回はせめてメモに書いてから臨みます。
参考にした資料
- デジタル庁「デジタル社会推進実践ガイドブック DS-464-2 APIテクニカルガイドブック」（2024年9月30日）PDFへのリンク
- デジタル庁「政府相互運用性フレームワーク（GIF）」https://www.digital.go.jp/policies/data_strategy_government_interoperability_framework
- OpenAPI Specification（OpenAPI Initiative）https://spec.openapis.org/oas/latest.html
