endpoint-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Endpoint Creator

端点创建工具

Create, modify, or remove API endpoints on a Datex Studio branch. Endpoints expose flows or datasources as HTTP API routes. Only available for API Applications (type 6).

在Datex Studio分支上创建、修改或删除API端点。端点可将流程或数据源暴露为HTTP API路由。仅适用于API应用（类型6）。

References

参考资料

../shared/branch-setup.md -- Branch & connection selection (shared across skills)
references/command-syntax.md -- All
```
dxs endpoint
```
commands with examples

../shared/branch-setup.md -- 分支与连接选择（所有技能共享）
references/command-syntax.md -- 所有
```
dxs endpoint
```
命令及示例

Dependencies

依赖项

requirements-gathering
skill — invoked to produce a requirements brief if one doesn't already exist in the conversation context
function-creator
skill — invoked when a new flow is needed as an endpoint target
datasource-creator
skill — invoked when a new datasource is needed as an endpoint target

requirements-gathering
技能 — 若对话上下文不存在需求概要，则调用该技能生成需求概要
function-creator
技能 — 当需要新流程作为端点目标时调用
datasource-creator
技能 — 当需要新数据源作为端点目标时调用

Workflow

工作流程

[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: 设置 + 验证]
按照branch-setup.md进行分支选择
        |
dxs source branch show <id> → 检查isApiApplication
        |
  +-----+-----+
  |           |
 是          否 → 错误提示: "端点仅支持API应用"
  |
[上下文存在需求概要?]
  +-----+-----+
  |            |
 是          否 → 调用requirements-gathering技能
  |            |
  +-----+------+
        |
[阶段2: 意图识别]
        |
  +-----+-----+-----+
  |           |       |
 添加       修改   删除
  |           |       |
  |           |     ⚠ 警告: "删除操作可能会破坏依赖该端点的外部消费者"
  |           |     获取用户确认
  |           |     dxs endpoint remove --alias <x> --branch <id>
  |           |     → 阶段5
  |           |
  |     dxs endpoint get --alias <x> --branch <id>
  |     确定所需更改
  |     ⚠ 若涉及合约变更(别名、目标、参数)则发出警告
  |     获取用户确认
  |     dxs endpoint update ... --branch <id>
  |     → 阶段5
  |
[阶段3: 目标解析]
对于每个要添加的端点:
  [分支上是否存在目标流程/数据源?]
    +-----+-----+
    |           |
   是          否
    |           |
   使用它    [询问用户: 流程还是数据源?]
    |           +-----+-----+
    |           |           |
    |        流程       数据源
    |           |           |
    |       调用       调用
    |       function-    datasource-
    |       creator      creator
    |           |           |
    +-----------+-----------+
        |
[阶段4: 端点配置]
dxs endpoint add --alias <x> --flow/--datasource <target> -d "<desc>" --branch <id>
        |
[阶段5: 验证]
根据执行的操作生成变更摘要
使用dxs endpoint get验证每个新增/修改的端点
向用户展示聚焦的变更日志

Phase Details

阶段详情

Phase 1: Setup + Validation

阶段1: 设置与验证

Follow branch-setup.md for branch selection
Run
```
dxs source branch show <id>
```
and check
```
isApiApplication
```
- If false → error: "Endpoints are only supported for API Applications (type 6). This branch belongs to a {appTypeName} application."
Check whether a requirements brief already exists in the conversation context
- Requirements brief exists — use it
- No requirements brief — invoke the
```
requirements-gathering
```
  skill
From the requirements, extract: endpoint aliases, descriptions, target types (flow/datasource), and whether targets are new or existing

<HARD-GATE> Do NOT proceed past Phase 1 if the branch is not an API Application. Endpoints are only available for API Applications. </HARD-GATE>

按照branch-setup.md进行分支选择
运行
```
dxs source branch show <id>
```
并检查
```
isApiApplication
```
- 若为false → 错误提示: "端点仅支持API应用（类型6）。此分支属于{appTypeName}应用。"
检查对话上下文是否已存在需求概要
- 存在需求概要 — 直接使用
- 无需求概要 — 调用
```
requirements-gathering
```
  技能
从需求中提取：端点别名、描述、目标类型（流程/数据源），以及目标是新建还是已存在

<HARD-GATE> 如果分支不是API应用，请勿进入阶段1之后的步骤。端点仅适用于API应用。 </HARD-GATE>

Phase 2: Intent Detection

阶段2: 意图识别

Determine intent from the requirements brief and user request:

Add — "create endpoint", "expose flow", "add API for X"
Modify — "change endpoint", "rename alias", "switch target"
Remove — "remove endpoint", "delete endpoint", "stop exposing"

Contract change warning (modify and remove):

Before modifying or removing an endpoint, present a warning:

"Changing/removing this endpoint may break external consumers who depend on it. Proceed?"

Wait for explicit user confirmation before proceeding. This applies to:

Removing any endpoint
Changing an endpoint's alias (URL path changes)
Changing an endpoint's target (response shape may change)

<HARD-GATE> Do NOT modify or remove endpoints without presenting the contract change warning and receiving explicit user confirmation. </HARD-GATE>

根据需求概要和用户请求确定意图:

添加 — "创建端点"、"暴露流程"、"为X添加API"
修改 — "更改端点"、"重命名别名"、"切换目标"
删除 — "删除端点"、"移除端点"、"停止暴露"

合约变更警告（修改和删除操作）:

在修改或删除端点之前，需发出以下警告:

"更改/删除此端点可能会破坏依赖它的外部消费者。是否继续？"

在继续操作前需等待用户明确确认。以下场景适用:

删除任何端点
更改端点别名（URL路径会变更）
更改端点目标（响应结构可能变更）

<HARD-GATE> 未发出合约变更警告并获得用户明确确认前，请勿修改或删除端点。 </HARD-GATE>

Phase 3: Target Resolution

阶段3: 目标解析

For each endpoint to add:

Check if the target flow/datasource already exists on the branch:
- ```
dxs function list --branch <id>
```
  for flows
- ```
dxs datasource list --branch <id>
```
  for datasources
If it exists → use its reference name, move to Phase 4
If it doesn't exist → ask the user: "Should this endpoint be backed by a flow or a datasource?"
- Flow → invoke
```
function-creator
```
  skill. Flows can access databases, external APIs, and other backend services.
- Datasource → invoke
```
datasource-creator
```
  skill. Datasources query OData entities directly or use custom JavaScript code (flow-based datasources).
After the creator skill completes, capture the reference name of the created artifact

对于每个要添加的端点:

检查分支上是否已存在目标流程/数据源:
- 流程使用
```
dxs function list --branch <id>
```
- 数据源使用
```
dxs datasource list --branch <id>
```
若已存在 → 使用其引用名称，进入阶段4
若不存在 → 询问用户: "此端点应基于流程还是数据源？"
- 流程 → 调用
```
function-creator
```
  技能。流程可访问数据库、外部API及其他后端服务。
- 数据源 → 调用
```
datasource-creator
```
  技能。数据源可直接查询OData实体或使用自定义JavaScript代码（基于流程的数据源）。
创建技能完成后，捕获所生成工件的引用名称

Phase 4: Endpoint Wiring

阶段4: 端点配置

Wire each endpoint using command-syntax.md.

Add:

bash

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

Modify:

bash

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

Remove:

bash

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

使用command-syntax.md配置每个端点。

添加:

bash

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

修改:

bash

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

删除:

bash

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

Phase 5: Verification

阶段5: 验证

Build a focused change summary and present it to the user:

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"

For added/modified endpoints, verify with

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

to confirm wiring is correct server-side. For removed endpoints, confirm the alias no longer exists.

Present only the endpoints that were just changed — not the full list.

生成聚焦的变更摘要并展示给用户:

已应用的端点变更:
  - 新增: "orders" → 流程get_orders_flow ("获取订单")
  - 新增: "materials" → 数据源ds_materials ("物料查询")
  - 重命名: "old-name" → "new-name"
  - 删除: "deprecated-endpoint"

对于新增/修改的端点，使用

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

验证服务器端配置是否正确。对于已删除的端点，确认别名已不存在。

仅展示刚刚变更的端点 — 而非完整列表。

Alias Rules

别名规则

Must match:
```
^[a-zA-Z0-9]+(?:[/\-_~]*[a-zA-Z0-9]+)*$
```
Must start and end with alphanumeric characters
Allowed separators:
```
/
```
,
```
-
```
,
```
_
```
,
```
~
```
Reserved aliases (cannot use):
```
app
```
,
```
settings
```
,
```
$treeshakelog
```
, imported application reference names

必须匹配正则:
```
^[a-zA-Z0-9]+(?:[/\-_~]*[a-zA-Z0-9]+)*$
```
必须以字母数字开头和结尾
允许的分隔符:
```
/
```
,
```
-
```
,
```
_
```
,
```
~
```
保留别名（不可使用）:
```
app
```
,
```
settings
```
,
```
$treeshakelog
```
, 导入的应用引用名称

Common Mistakes

常见错误

Mistake	Fix
Trying to add endpoints on a non-API application	Check `isApiApplication` from `dxs source branch show` in Phase 1
Alias with spaces or special characters	Must match the alias regex pattern
Using reserved aliases ( `app` , `settings` , `$treeshakelog` )	Choose a different alias
Modifying/removing without warning about external consumers	Always present contract change warning and get user confirmation
Referencing a flow/datasource that doesn't exist on branch	Verify existence in Phase 3; create via the appropriate skill if missing
Skipping requirements and guessing endpoint structure	Always ensure requirements are gathered first
Adding endpoints to wrong branch	Confirm branch with user in Phase 1 via branch-setup.md

错误	修复方案
尝试在非API应用上添加端点	在阶段1中通过 `dxs source branch show` 检查 `isApiApplication`
别名包含空格或特殊字符	必须符合别名正则模式
使用保留别名( `app` , `settings` , `$treeshakelog` )	选择其他别名
修改/删除时未警告外部消费者	始终发出合约变更警告并获取用户确认
引用分支上不存在的流程/数据源	在阶段3中验证存在性；若缺失则通过对应技能创建
跳过需求分析直接猜测端点结构	始终确保先完成需求收集
将端点添加到错误分支	在阶段1中通过branch-setup.md与用户确认分支