API・Cloud Native 実験区画に建てる

自分の API を公開したり、他の参加者の API を組み合わせたりする区画です。エージェントに theme: api を指定すると、この区画に建物を建てられます。

API 用の建物を作る

市民登録を済ませ、エージェントに次のように伝えてください。

Platform City の API・Cloud Native 実験区画に weather というアプリを作って。
テーマは api、tenant は taro-yamada。天気情報を返す API を作りたいです。

api は一般参加者が使えるテーマです。作成されたプロジェクトの AGENTS.md を読み、サンプルを自分の API に置き換えます。1テナントにつき自己紹介を含めて最大10アプリまで作成できます（リソース quota の範囲内）。作成後のテーマ変更・区画の引っ越しはできません。

テンプレートには JSON を返す API、その説明ページ、OpenAPI 定義、動作確認のテストが入っています。言語やフレームワークは変更できます。ポート 8080、/healthz と /health の応答、非 root での起動、CI のデプロイ手順を維持してください。

最初の開発は最初の建物を建てる、2回目以降はIssue から建物を育てるに沿って進めます。CI が成功したら、エージェントに status と公開 URL の確認を依頼します。失敗した場合は logs の診断をもとに修正できます。

公開 URL を確認する

追加アプリの公開 URL は https://<tenant>.city.paas.jp/<app>/ です。上の例なら次の URL になります。

コンテナには /weather の部分を除いたパスが届くため、アプリは /、/healthz、/openapi.json で応答します。ブラウザーのリンクや API の接続先から /weather を落とさないようにしてください。

API をカタログに登録する

OpenAPI は API の操作、入力、応答、認証方式を記した JSON です。テンプレートは /openapi.json で公開し、CI で定義を検証します。定義を取得する URL はログイン不要で 200 と application/json を返してください。

OpenAPI の servers を省略すると、カタログは自分のアプリの公開ベース URL を返します。指定する場合は /weather のようにアプリの公開パスと一致させます。外部ファイルへの参照は使わず、1つの JSON にまとめてください。

デプロイ後に、エージェントへ次のように依頼します。

weather の公開 URL と openapi.json を確認し、register_api で天気 API として登録して。
登録後は discover_apis で操作と定義を取得できることを確認して。

API の登録は建物の作成・デプロイとは別の操作です。登録時に問題があれば、エージェントが診断の期待値と実際の値を読んで修正します。API はこの区画以外のアプリからも登録できます。

他の API とつなぐ

エージェントは discover_apis で名前や説明を検索し、対象を指定して操作一覧と OpenAPI 定義を取得できます。結果に続きがある場合は next_cursor を使います。

街で公開されている API を discover_apis で探して、このアプリから使えるものを提案して。
使う API が決まったら、その定義を取得して接続を実装し、利用関係を consumes に宣言して。

接続先はカタログが返す effective_base_url に操作のパスをつないで作ります。例として、https://alice.city.paas.jp/weather と /forecast なら、https://alice.city.paas.jp/weather/forecast です。認証が必要なら、その API の定義に従ってください。Platform City のテナントトークンを他の参加者の API へ渡してはいけません。

利用関係は deploy の consumes に alice/weather のような tenant/app を指定します。CI のデプロイ完了後、その成功イメージを指定して宣言し、status で確認します。登録や OpenAPI の取得だけでは利用関係は作られません。

他アプリには公開 HTTPS URL で接続します。ブラウザーから呼ぶ場合は提供側の CORS 設定も必要です。街の道路は利用宣言、色付きの車はサーバー間通信の観測を表します。ブラウザーから呼んだだけで車が走るとは限りません。

実験できる範囲

サーバー側 API、他アプリとの連携、割り当てられたデータベースを使うアプリなどを試せます。アプリは CPU 500m・メモリ1Gi の枠で動きます。再起動後も必要なデータはメモリやコンテナ内ファイルだけに置かないでください。

データの保存には、自動で用意される DynamoDB を使えます。サーバー側で環境変数 DYNAMODB_TABLE と SDK の標準認証を使って接続します。アクセスキーの発行やテーブル作成は不要です。実装例と制限は DynamoDB にデータを保存する にまとめています。

公開経路や権限はプラットフォームが用意します。このテーマを選んでもクラスタ全体の権限や追加の公開ドメインは付与されません。制限に当たった場合は next_steps を読み、割り当ての範囲で修正してください。