iii-http-endpoints

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HTTP Endpoints

HTTP 端点

Comparable to: Express, Fastify, Flask

同类工具：Express、Fastify、Flask

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every HTTP endpoint needs all of them.

Each route is a registered function bound to a path and method via an HTTP trigger
The handler receives an ApiRequest object containing
```
body
```
,
```
path_params
```
,
```
headers
```
, and
```
method
```
Handlers return
```
{ status_code, body, headers }
```
to shape the HTTP response
RestApiModule serves all registered routes on port 3111
Path parameters use colon syntax (e.g.
```
/users/:id
```
) and arrive in
```
path_params
```

请根据任务需求选用以下概念，并非每个HTTP端点都需要用到全部概念。

每个路由都是一个已注册函数，通过HTTP触发器绑定到特定路径和请求方法
处理器会接收一个包含
```
body
```
、
```
path_params
```
、
```
headers
```
和
```
method
```
的ApiRequest对象
处理器返回
```
{ status_code, body, headers }
```
来构建HTTP响应
RestApiModule在3111端口提供所有已注册路由的服务
路径参数使用冒号语法（例如
```
/users/:id
```
），并会被解析到
```
path_params
```
中

Architecture

架构

HTTP request → RestApiModule (port 3111) → registerTrigger route match (method + path) → registerFunction handler (receives ApiRequest) → { status_code, body, headers } response

iii Primitives Used

使用的iii原语

Primitive	Purpose
`registerFunction`	Define the handler for a route
`registerTrigger({ type: 'http' })`	Bind a route path and method to a function
`config: { api_path: '/path', http_method: 'GET' }`	Route configuration on the trigger

原语	用途
`registerFunction`	定义路由的处理器函数
`registerTrigger({ type: 'http' })`	将路由路径和请求方法绑定到函数
`config: { api_path: '/path', http_method: 'GET' }`	触发器上的路由配置参数

Reference Implementation

参考实现

See ../references/http-endpoints.js for the full working example — a REST API with parameterized routes handling GET and POST requests.

Also available in Python: ../references/http-endpoints.py

Also available in Rust: ../references/http-endpoints.rs

完整的工作示例请查看../references/http-endpoints.js —— 这是一个包含参数化路由、可处理GET和POST请求的REST API。

同时提供Python版本：../references/http-endpoints.py

同时提供Rust版本：../references/http-endpoints.rs

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization
```
registerFunction(id, handler)
```
— define the route handler

registerTrigger({ type: 'http', config: { api_path, http_method } })

— bind path and method

```
req.body
```
— parsed request body for POST/PUT
```
req.path_params
```
— extracted path parameters

return { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } }

— response shape

```
const logger = new Logger()
```
— structured logging per handler

采用此模式的代码通常会包含以下内容（按需使用）：

```
registerWorker(url, { workerName })
```
—— Worker初始化
```
registerFunction(id, handler)
```
—— 定义路由处理器

registerTrigger({ type: 'http', config: { api_path, http_method } })

—— 绑定路径和请求方法

```
req.body
```
—— POST/PUT请求的已解析请求体
```
req.path_params
```
—— 提取出的路径参数

return { status_code: 200, body: { data }, headers: { 'Content-Type': 'application/json' } }

—— 响应结构

```
const logger = new Logger()
```
—— 为每个处理器添加结构化日志

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Add more routes by registering additional functions and HTTP triggers with distinct paths or methods
Use
```
path_params
```
for resource identifiers (e.g.
```
/orders/:orderId
```
)
Return appropriate status codes (201 for creation, 404 for not found, 400 for bad input)
For authenticated routes, inspect
```
req.headers
```
for tokens or API keys
Chain work behind an endpoint by enqueuing to a queue after returning a 202 Accepted

请根据任务需求采用以下适配方式：

通过注册更多函数和具有不同路径或请求方法的HTTP触发器来添加更多路由
使用
```
path_params
```
传递资源标识符（例如
```
/orders/:orderId
```
）
返回合适的状态码（创建成功返回201，资源不存在返回404，输入错误返回400）
对于需要认证的路由，检查
```
req.headers
```
中的令牌或API密钥
返回202 Accepted状态后，将后续任务加入队列，实现端点后的任务链式处理

Pattern Boundaries

模式适用边界

If the task is about calling external HTTP APIs from iii functions, prefer
```
iii-http-invoked-functions
```
.
If async processing is needed behind the endpoint, prefer
```
iii-queue-processing
```
for the background work.
Stay with
```
iii-http-endpoints
```
when iii owns the route and handles the inbound request directly.

如果任务是从iii函数调用外部HTTP API，建议使用
```
iii-http-invoked-functions
```
。
如果端点需要异步处理，建议使用
```
iii-queue-processing
```
来处理后台任务。
当iii负责路由并直接处理入站请求时，使用
```
iii-http-endpoints
```
。

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-http-endpoints
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

当任务主要涉及iii引擎中的
```
iii-http-endpoints
```
时，使用此技能。
当请求直接要求使用此模式或等效实现时触发。

Boundaries

限制条件

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.

切勿将此技能作为无关任务的通用备选方案。
当更特定的iii技能更适合时，不得使用此技能。
在应用此技能中的示例之前，务必验证环境和安全约束。