小温室の屋根が、低い音を立てた。
開くまで、あと九十秒。
外は冬の夜だ。窓ガラスの端が白く曇り、温室の中では細い苗が二十鉢、暖かな土に葉を広げている。
イトの画面には、大きな数字が出ていた。
外気温 30℃ API受信 成功 高温のため、屋根を開きます
緑の完了灯もついている。
「できた」
イトは机の上の完了札を立てた。
この一晩、自動換気が問題なく動けば、翌朝の発表会で「API連携完成」と紹介できる。もう何日も、温度の数字が画面へ届くところまでは試していた。
イト
外が30℃なら、屋根を開けて熱を逃がせばいい。APIも成功って返してる
ユイ
外が30℃、ですか。窓はこんなに冷たいのに？
ピコ
数字は届いた。でも、その数字が何を意味する返事なのか、まだ開いていないよ
屋根が開くまで、あと七十六秒。
「30」は、30℃ではなかった
イトは、画面の裏側を開いた。
温度APIへ送ったお願いは二通ある。
一通目は、現在の外気温を返す本番窓口。
もう一通は、接続試験に使っていた見本窓口だ。
ピコが二つの返事を、透明なカードに変えた。
本番窓口のカードには、温度がない。
{
"error": "authentication_required",
"endpoint": "live"
}試験窓口のカードには、数字がある。
{
"temperature": 30,
"unit": "F",
"observedAt": "yesterday",
"source": "demo"
}イトの画面は、二枚のうちtemperatureがある方だけを見つけた。
単位も、測った時刻も、見本データだという印も捨て、数字の後ろへ勝手に℃を付けていた。
「30は届いた。でも、昨日の30°Fだった」
華氏30度は、摂氏なら氷点下に近い。
温室の屋根を開ければ、暖めるどころか冷たい外気が入る。
屋根が開くまで、あと五十八秒。
JSONが読めても、意味は決まらない
二枚の返事は、どちらもJSONとして読めた。
JSONは、文字列、数値、真偽値、null、object、arrayなどを使って構造化データを表す形式だ。RFC 8259では、objectをnameとvalueの組み合わせとして表す基本ルールが定められている。
けれど、波括弧が閉じていることは、その温度が現在の本番値だという証明ではない。
30が温度なのか、何の単位なのか、いつどこで測ったのか、画面へ出してよい値なのか。それはJSONの記号だけでは決まらない。
APIは、アプリやサービスが決まった窓口へお願いを送り、データや機能の返事を受け取るための接点だ。
窓口の場所がendpoint。
何を送り、どんな返事があり、どの認証が必要かは、そのAPIの約束で決まる。
OpenAPI Specificationのような記述形式では、operation、parameter、response、schema、security requirementsをAPI descriptionへ表せる。
ただし、仕様書があれば現実の値が自動で正しくなるわけではない。呼び出す側も、届いた返事が約束どおりか、不足時に何をするかを決める必要がある。
屋根が開くまで、あと四十秒。
イトが選べる三つの道
ピコが机へ三枚の札を置いた。
- 屋根を開ける
- 数字を隠す
- 自動を切る
一枚目なら、緑の成功表示を信じて予定どおり動かせる。けれど、氷点下に近い外気が苗へ入る。
二枚目なら、利用者から30℃を見えなくできる。けれど、屋根を開ける命令は止まらない。
三枚目なら、今夜の自動運転は未完成になる。翌朝の発表も取り消しだ。
イトは完了札を見た。
発表用の写真には、緑の灯が必要だった。
屋根が開くまで、あと二十七秒。
イトは三枚目の札を取った。
温室へ伸びる青い自動連結plugを、自分の手で引き抜く。
「自動を切る」
緑の完了灯が消えた。
屋根の歯車も止まった。
外気を示す画面からは、30℃が消えた。
代わりに灰色の表示が残る。
現在値を確認できません 自動換気を停止しました
カウントは、あと十三秒で止まった。
閉じた屋根の下で、直接測る
マコトが、APIとはつながっていない棒状の温度計を窓の外へ出した。
数字は、2℃を示した。
屋根は閉じている。
苗の葉は揺れなかった。
冷たい空気も入らない。
マコト
止めた結果は見えた。次は、どの窓口の、どの返事なら自動へ渡せるかを決めよう
ユイ
本番窓口は温度を返していません。認証に失敗した返事を、見本の温度で埋めてはいけませんね
イト
成功したのはJSONを受け取ったことだけだった。温室を動かしていい成功じゃなかった
HTTPの401 responseは、対象へ使える認証情報がないため、そのrequestが適用されていないことを示す。HTTP SemanticsのRFC 9110でも、401と認証challengeの意味が定められている。
この物語の温室APIと自動換気はフィクションだ。実在する気象APIや温室制御が同じfallbackをするという話ではない。認証エラー時に古い見本値を本番値として使ったのは、イトの試験画面の欠陥だ。
返事の形と、返事の意味を分ける
イトは、受け取るカードの条件を書き直した。
本番のendpointから返っている 認証に失敗していない
temperatureが数値であるunitが許可した単位であるobservedAtが新しいsourceがliveである
どれか一つでも足りなければ、画面へ温度を表示しない。
屋根も動かさない。
JSON Schemaは、JSON documentの構造、型、必要項目などを記述して検証するための言語だ。返事が約束した形か確かめる助けになる。
けれど、schemaを通った2℃が現実でも本当に2℃かは、別の問題だ。sensorの故障や古い値まで、波括弧は見抜いてくれない。
だからイトは、次の三つを分けた。
JSONとして読める APIの約束した形である 今の現実と照合できる
画面の成功表示も、一つにまとめなかった。
接続できた 認証できた 現在値を受け取った 自動制御へ使った
途中で止まれば、最後だけを緑にしない。
緑の完了灯は、戻さなかった
認証情報を更新すると、本番窓口から新しい返事が来た。
{
"temperature": 2,
"unit": "C",
"observedAt": "now",
"source": "live"
}画面の2℃と、窓の外の温度計が並ぶ。
けれど、イトは自動連結plugを挿さなかった。
一回値が合っただけでは、夜通し安全に動く試験にはならない。
翌朝の発表画面から、「API連携完成」の文字を消した。
代わりに表示したのは、二枚の返事だ。
昨日の見本窓口から来た30°F。
今の本番窓口から来た2℃。
同じJSONの箱に入っていても、使ってよい返事は同じではない。
温室の屋根は閉じたままだ。
外されたplugの横では、緑の完了札が伏せられている。
苗の前には、今夜の手動確認表と、次に試す失敗条件が増えた。
イトは上着を着直し、最初の時刻へ丸を付けた。
帰宅予定は遅れ、発表もなくなった。
それでも、画面の「成功」を苗の安全より先に戻すことはしなかった。
次回：お願いと返事を運ぶ約束
二枚のAPI response cardを片づけると、それぞれの裏から細い紙が出てきた。
GET。
header。
status。
body。
イトは、本番窓口へ送った一通目を持ち上げる。
「APIの窓口は分かった。でも、このお願いと返事は、何に乗って運ばれたんだろう」
ピコが、温室とAPI受付の間へHTTPと書かれた橋をかけた。
次回、ピコルート第64話。
HTTPのお願い票には、何が入っている？