endpoint-creator

エンドポイント作成

Datex Studio のブランチで、API エンドポイントを作成、変更、または削除します。エンドポイントは、フローやデータソースを HTTP API ルートとして公開します。API アプリケーション（type 6）でのみ利用できます。

参考資料

• ../datex-studio-shared/branch-setup.md -- ブランチと接続の選択（各スキルで共通）
• references/command-syntax.md -- dxs endpoint コマンドの一覧と例

依存関係

• requirements-gathering スキル — 会話のコンテキストに要件概要がまだ存在しない場合、要件概要を作成するために呼び出します
• function-creator スキル — エンドポイントのターゲットとして新しいフローが必要な場合に呼び出します
• datasource-creator スキル — エンドポイントのターゲットとして新しいデータソースが必要な場合に呼び出します

ワークフロー

[Phase 1: Setup + Validation]
Follow branch-setup.md for branch selection
        |
dxs source branch show <id> → check isApiApplication
        |
  +-----+-----+
  |           |
 YES          NO → error: "Endpoints only supported for API Applications"
  |
[requirements brief in context?]
  +-----+-----+
  |            |
 YES          NO → invoke requirements-gathering skill
  |            |
  +-----+------+
        |
[Phase 2: Intent Detection]
        |
  +-----+-----+-----+
  |           |       |
 ADD       MODIFY   REMOVE
  |           |       |
  |           |     ⚠ warn: "Removing may break external consumers"
  |           |     get user confirmation
  |           |     dxs endpoint remove --alias <x> --branch <id>
  |           |     → Phase 5
  |           |
  |     dxs endpoint get --alias <x> --branch <id>
  |     determine changes needed
  |     ⚠ warn if contract change (alias, target, params)
  |     get user confirmation
  |     dxs endpoint update ... --branch <id>
  |     → Phase 5
  |
[Phase 3: Target Resolution]
For each endpoint to add:
  [does target flow/datasource exist on branch?]
    +-----+-----+
    |           |
   YES          NO
    |           |
   use it    [ask user: flow or datasource?]
    |           +-----+-----+
    |           |           |
    |        FLOW       DATASOURCE
    |           |           |
    |       invoke       invoke
    |       function-    datasource-
    |       creator      creator
    |           |           |
    +-----------+-----------+
        |
[Phase 4: Endpoint Wiring]
dxs endpoint add --alias <x> --flow/--datasource <target> -d "<desc>" --branch <id>
        |
[Phase 5: Verification]
Build change summary from actions taken
Verify each added/modified endpoint with dxs endpoint get
Present focused changelog to user

フェーズの詳細

フェーズ 1：セットアップと検証

1. ブランチの選択については branch-setup.md に従います
2. dxs source branch show <id> を実行し、isApiApplication を確認します
   • false の場合 → エラー：「エンドポイントは API アプリケーション（type 6）でのみサポートされています。このブランチは {appTypeName} アプリケーションに属しています。」
3. 会話のコンテキストに要件概要がすでに存在するか確認します
   • 要件概要が存在する — それを使用します
   • 要件概要が存在しない — requirements-gathering スキルを呼び出します
4. 要件から、エンドポイントのエイリアス、説明、ターゲットの種類（フロー／データソース）、およびターゲットが新規か既存かを抽出します

ブランチが API アプリケーションでない場合、フェーズ 1 を超えて進めないでください。エンドポイントは API アプリケーションでのみ利用できます。

フェーズ 2：意図の判定

要件概要とユーザーの依頼から意図を判定します。

• 追加 — 「エンドポイントを作成」「フローを公開」「X の API を追加」
• 変更 — 「エンドポイントを変更」「エイリアスの名前を変更」「ターゲットを切り替え」
• 削除 — 「エンドポイントを削除」「エンドポイントの公開を停止」

コントラクト変更の警告（変更および削除）：

エンドポイントを変更または削除する前に、次の警告を提示します。

「このエンドポイントを変更または削除すると、依存している外部の利用者に影響する可能性があります。続行しますか？」

続行する前に、ユーザーから明示的な確認を得てください。これは次の場合に適用されます。

• 任意のエンドポイントを削除する場合
• エンドポイントのエイリアスを変更する場合（URL パスが変わります）
• エンドポイントのターゲットを変更する場合（レスポンスの形式が変わる可能性があります）

コントラクト変更の警告を提示し、ユーザーから明示的な確認を得ることなく、エンドポイントを変更または削除しないでください。

フェーズ 3：ターゲットの解決

追加する各エンドポイントについて、次の手順を行います。

1. ターゲットのフロー／データソースがブランチにすでに存在するか確認します。
   • フローの場合は dxs function list --branch <id>
   • データソースの場合は dxs datasource list --branch <id>
2. 存在する場合 → その参照名を使用し、フェーズ 4 に進みます
3. 存在しない場合 → ユーザーに「このエンドポイントのバックエンドには、フローとデータソースのどちらを使用しますか？」と尋ねます
   • フロー → function-creator スキルを呼び出します。フローはデータベース、外部 API、その他のバックエンドサービスにアクセスできます。
   • データソース → datasource-creator スキルを呼び出します。データソースは OData エンティティを直接クエリするか、カスタム JavaScript コード（フローベースのデータソース）を使用します。
4. 作成スキルの完了後、作成されたアーティファクトの参照名を取得します

フェーズ 4：エンドポイントの接続

command-syntax.md に従って、各エンドポイントを接続します。

追加：

dxs endpoint add --alias <alias> --flow/--datasource <ref_name> \
  --description "<desc>" --branch <id>

変更：

dxs endpoint update --alias <alias> [--new-alias/--flow/--datasource/-d/--module] \
  --branch <id>

削除：

dxs endpoint remove --alias <alias> --branch <id>

フェーズ 5：検証

変更内容に絞った概要を作成し、ユーザーに提示します。

Endpoint changes applied:
  - Added: "orders" → flow get_orders_flow ("Get orders")
  - Added: "materials" → datasource ds_materials ("Materials lookup")
  - Renamed: "old-name" → "new-name"
  - Removed: "deprecated-endpoint"

追加または変更したエンドポイントについては、dxs endpoint get --alias <alias> --branch <id> で確認し、サーバー側で正しく接続されていることを検証します。削除したエンドポイントについては、そのエイリアスが存在しなくなったことを確認します。

直近で変更したエンドポイントのみを提示し、一覧全体は提示しないでください。

エイリアスのルール

• 次のパターンに一致する必要があります：^[a-zA-Z0-9]+(?:[/\-_~]*[a-zA-Z0-9]+)*$
• 英数字で始まり、英数字で終わる必要があります
• 使用できる区切り文字：/、-、_、~
• 予約済みのエイリアス（使用不可）：app、settings、$treeshakelog、インポートされたアプリケーションの参照名

よくある間違い

間違い	修正方法
API ではないアプリケーションにエンドポイントを追加しようとする	Phase 1 で dxs source branch show の isApiApplication を確認します
エイリアスにスペースや特殊文字を使う	エイリアスの正規表現パターンに一致させる必要があります
予約済みのエイリアス（app、settings、$treeshakelog）を使う	別のエイリアスを選びます
外部の利用者への警告なしに変更または削除する	必ず契約変更の警告を提示し、ユーザーの確認を得ます
ブランチに存在しないフロー／データソースを参照する	Phase 3 で存在を確認します。ない場合は、該当するスキルを使って作成します
要件を確認せず、エンドポイントの構造を推測する	必ず最初に要件を収集します
間違ったブランチにエンドポイントを追加する	Phase 1 で branch-setup.md を使い、ユーザーにブランチを確認します

---

編集後、post-edit-verification を実行して、説明／JSON／スキーマの違反を検出します。最終レビューでは、component-validator を実行します。