API仕様 API spec

モバイルアプリが利用する API を、接続先ごとに分類して一覧化します。 現行設計では Cloudflare Workers BFF（/v1/*、OpenAPI 3.1）がクライアント向けの唯一の API 層で、 複雑なロジックは PostgreSQL RPC（Hyperdrive 経由で Workers から呼び出し）に集約しています。 Supabase は Auth / Realtime / PostgreSQL のみ（SDK 直接使用は Auth と Realtime の 2 系統に限定）。

This page catalogs every API the mobile app talks to, grouped by backend. In the current design the Cloudflare Workers BFF (/v1/*, OpenAPI 3.1) is the single client-facing API surface, with complex logic consolidated into PostgreSQL RPCs (invoked from Workers via Hyperdrive). Supabase is used only for Auth / Realtime / PostgreSQL — direct SDK use is limited to Auth and Realtime.

6.1 API設計方針API design principles

• 契約駆動：parky/api/openapi.json（OpenAPI 3.1）が正本。Workers 実装は @hono/zod-openapi で spec と連動し、CI で openapi.json を自動再生成する
• Contract-first: parky/api/openapi.json (OpenAPI 3.1) is the source of truth. Workers use @hono/zod-openapi to stay in sync with the spec; CI regenerates openapi.json
• 単一 API 層：クライアントが叩くのは /v1/*（Cloudflare Workers BFF）のみ。supabase.from() / rpc() / storage の直叩きは禁止（Auth と Realtime のみ SDK 直接利用）
• Single API surface: clients hit only /v1/* (the Cloudflare Workers BFF). Calling supabase.from() / rpc() / storage directly is forbidden — only Auth and Realtime use the SDK
• 認証：Supabase JWT を Authorization: Bearer <token> で BFF に送る。Workers が JWKS で検証してユーザースコープを立てる
• Authentication: send the Supabase JWT as Authorization: Bearer <token>. Workers verify via JWKS and scope the request to the user
• 認可：Workers がコード層で user_id スコープを徹底。RLS は Service Role でも二重防御として有効
• Authorization: Workers enforce user_id scoping in code. RLS stays on as defense-in-depth even under Service Role
• 複雑ロジック：トランザクション・集計は PostgreSQL RPC に切り出し、Workers から Hyperdrive 経由で呼び出す
• Complex logic: transactions and aggregations live as PostgreSQL RPCs, invoked from Workers via Hyperdrive
• 冪等性：副作用のある RPC は p_client_request_id (uuid) を引数に取り、二重発火を検知して no-op にする
• Idempotency: mutating RPCs take a p_client_request_id (uuid) and collapse duplicate calls into a no-op
• バージョニング：/v1/ プレフィックス。破壊的変更は /v2/ で並行運用し、旧版は最低 180 日維持
• Versioning: /v1/ prefix. Breaking changes ship as /v2/ and run in parallel for at least 180 days
• エラー：Workers は統一 JSON エラー形式（{ error: { code, message, request_id, issues? } }）。422 は Zod validation 失敗
• Errors: Workers return a unified JSON shape ({ error: { code, message, request_id, issues? } }). 422 means Zod validation failed
• インタラクティブ仕様：Swagger UI（Dev 固定）・Redoc（read-only）で直接叩ける
• Interactive spec: Swagger UI (Dev-only) / Redoc (read-only) let you explore the spec directly

6.2 API一覧API inventory

モバイルが叩く BFF エンドポイント（代表）BFF endpoints the mobile app calls (highlights)

完全な一覧と試し打ちは Swagger UI / Redoc を参照。 ここでは画面との対応を把握しやすい代表的な公開／自分向けエンドポイントのみ抜粋します。

For the full list and interactive tryouts use Swagger UI / Redoc. This table highlights the public and "me" endpoints that map 1-to-1 to screens.

RPC（PostgreSQL 関数）RPC (PostgreSQL functions)

Cloudflare Workers BFF エンドポイント（旧 Edge Functions を吸収）Cloudflare Workers BFF endpoints (absorbed the legacy Edge Functions)

Realtime 購読Realtime subscriptions

外部APIExternal APIs

6.3 API詳細仕様API details

create or replace function public.nearby_parking_lots(
  p_lat      numeric,
  p_lng      numeric,
  p_radius_m int     default 500,
  p_filters  jsonb   default '{}'::jsonb,
  p_limit    int     default 50
) returns table (
  id            uuid,
  name          text,
  address       text,
  lat           numeric,
  lng           numeric,
  distance_m    numeric,
  avg_rating    numeric,
  review_count  int,
  main_image    text,
  tags          text[]
) language sql stable
as $$
  select pl.id, pl.name, pl.address, pl.lat, pl.lng,
         st_distance(pl.location, st_makepoint(p_lng, p_lat)::geography) as distance_m,
         ...
$$;

{
  "max_height_m": 2.1,
  "tags": ["24h", "ev"],
  "open_now": true,
  "max_price": 2000,
  "entry_at": "2026-04-14T23:00:00+09:00",
  "exit_at":  "2026-04-15T09:00:00+09:00"
}

create or replace function public.create_parking_session(
  p_lot_id            uuid,
  p_vehicle_type      text,
  p_start_lat         numeric,
  p_start_lng         numeric,
  p_client_request_id uuid
) returns uuid language plpgsql
security definer as $$
declare v_session_id uuid;
begin
  -- 冪等性チェック
  select id into v_session_id
    from parking_sessions
    where client_request_id = p_client_request_id
      and user_id = auth.uid();
  if v_session_id is not null then
    return v_session_id;
  end if;

  -- 同時多重駐車防止
  if exists (select 1 from parking_sessions
             where user_id = auth.uid() and status = 'parking') then
    raise exception 'concurrent_session_not_allowed' using errcode = 'P0001';
  end if;

  insert into parking_sessions (...)
  returning id into v_session_id;

  -- 活動ログ
  insert into user_activity_logs (...) values (...);
  return v_session_id;
end$$;

POST /functions/v1/ai-search-parse
Authorization: Bearer <jwt>
Content-Type: application/json

{ "query": "池袋で23時から朝9時まで2000円以下", "locale": "ja" }

{
  "location": "池袋",
  "entry_at": "2026-04-14T23:00:00+09:00",
  "exit_at":  "2026-04-15T09:00:00+09:00",
  "max_price": 2000,
  "filters": [],
  "confidence": 0.94
}

{ "error": { "code": "unparseable", "message": "解釈できませんでした" } }

sequenceDiagram
  participant App
  participant EF as Cloudflare Workers
  participant Apple
  participant PG as PostgreSQL
  App->>EF: { platform, receipt, product_id }
  alt platform=ios
    EF->>Apple: verifyReceipt
    Apple-->>EF: { valid, expires_at }
  else platform=android
    EF->>Google: Play Developer API
    Google-->>EF: { valid, expires_at }
  end
  EF->>PG: upsert user_subscriptions
  EF->>PG: update app_users.premium
  EF-->>App: { subscription, status }

6.4 エラー仕様Error spec

統一エラー形式（Workers BFF）Unified error format (Workers BFF)

{
  "error": {
    "code": "string_code",     // スネークケースの機械可読コード
    "message": "日本語メッセージ",
    "details": { ... },        // 任意
    "request_id": "uuid"
  }
}

{
  "error": {
    "code": "string_code",     // snake_case machine-readable code
    "message": "human-readable message",
    "details": { ... },        // optional
    "request_id": "uuid"
  }
}

主要エラーコードKey error codes

DB 由来のエラーコード（Workers が翻訳して返す）DB-derived error codes (translated by Workers)

Workers は PostgreSQL の errcode を上記統一形式の error.code にマップしつつ、HTTP ステータスも適切に変換します。代表的なクラス：

Workers translate PostgreSQL's errcode into the unified shape above (error.code) and choose an appropriate HTTP status. Typical classes:

• 23505 (unique_violation) → 「既に存在します」
• 23505 (unique_violation) → "Already exists"
• 23514 (check_violation) → 「入力値が不正です」＋制約名を日本語化
• 23514 (check_violation) → "Invalid input value" plus a localized constraint name
• 42501 (insufficient_privilege) → forbidden 扱い
• 42501 (insufficient_privilege) → treated as forbidden
• PGRST116 (Supabase: 行が見つからない) → not_found 扱い
• PGRST116 (Supabase: row not found) → treated as not_found

6.5 レート制限Rate limiting