Back to Details

specsfy-specialist-web-api-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Design de APIs web

Web API设计

Quando usar

适用场景

Acionar ao projetar ou revisar contratos HTTP, REST, JSON, webhooks ou descrições OpenAPI para consumidores internos ou externos.
Acionar para decisões de recursos, métodos, status, erros, paginação, idempotência, concorrência, autenticação e compatibilidade.
Não acionar para RPC ou eventos como se fossem recursos HTTP sem primeiro confirmar o estilo do contrato real.
Combinar com
```
$specsfy-specialist-application-security
```
para threat modeling, credenciais, abuso e trust boundaries.

在为内部或外部消费者设计或评审HTTP、REST、JSON、Webhook或OpenAPI契约描述时使用。
在进行资源、方法、状态码、错误处理、分页、idempotency、并发、认证及兼容性相关决策时使用。
请勿在未确认实际契约风格的情况下，将其当作HTTP资源来处理RPC或事件。
可结合
```
$specsfy-specialist-application-security
```
进行威胁建模、凭证管理、滥用防护及信任边界划分。

Fluxo

流程

Descobrir consumidores, casos de uso, estilo existente, volume, latência, disponibilidade, trust boundaries e política de compatibilidade.
Modelar recursos, identidade, relações, invariantes e ownership sem expor tabelas ou objetos internos como contrato por conveniência.
Definir operações, schemas, headers, status e Problem Details; registrar a semântica de retry por operação usando references/standards.md.
Projetar autenticação, autorização por recurso/tenant, idempotência, precondições e concorrência antes de implementar handlers.
Especificar paginação, filtros, ordenação determinística, limites, rate limiting e comportamento diante de dados mutáveis.
Materializar OpenAPI/JSON Schema e contract tests positivos, negativos e de compatibilidade executados contra a implementação.
Definir logs, métricas, correlação, depreciação, migração e critérios para remover comportamento antigo sem quebrar consumidores conhecidos.

明确消费者、使用场景、现有风格、流量规模、延迟要求、可用性需求、信任边界及兼容性策略。
建模资源、身份、关系、不变量及归属权，切勿为了便利而将内部数据表或对象直接暴露为契约。
定义操作、Schema、请求头、状态码及Problem Details；通过references/standards.md记录各操作的重试语义。
在实现处理程序之前，设计认证、基于资源/租户的授权、idempotency、前置条件及并发控制机制。
指定分页、过滤、确定性排序、限制条件、速率限制及可变数据的处理行为。
生成OpenAPI/JSON Schema，并针对实现执行正向、反向及兼容性契约测试。
定义日志、指标、链路追踪、废弃策略、迁移方案及移除旧行为的判定标准，确保不会影响已知消费者。

Padrões

最佳实践

Usar semântica HTTP coerente e status específicos.
Manter formato de erro estável, acionável e sem vazamento.
Usar cursor quando dados mudam durante paginação extensa.
Tornar criação/retry seguros com chave de idempotência quando necessário.
Proteger webhooks com assinatura, timestamp, replay defense e reentrega.
Evitar breaking changes silenciosas e campos com semântica ambígua.
Não expor modelo de persistência como contrato por conveniência.

使用一致的HTTP语义及特定状态码。
保持错误格式稳定、可操作且无信息泄露。
当分页过程中数据发生变化时，使用游标（cursor）分页。
在必要时，通过幂等键（idempotency key）确保创建/重试操作的安全性。
使用签名、时间戳、重放防护及重传机制保护Webhook。
避免静默破坏性变更及语义模糊的字段。
切勿为了便利而将持久化模型直接暴露为契约。

Antipadrões

反模式

Responder
```
200
```
para todo resultado e codificar falha apenas no body; caches, clientes e observabilidade perdem a semântica do protocolo.
Repetir POST após timeout sem idempotência ou reconciliação; uma resposta perdida pode duplicar cobrança, pedido ou efeito externo.
Paginar por offset em coleção grande e mutável sem ordenação estável; itens são duplicados ou omitidos entre páginas.
Autorizar somente no endpoint/lista e não no recurso carregado; IDs válidos atravessam tenants ou escopos.
Versionar a URL para toda mudança aditiva; multiplica contratos ativos sem resolver disciplina de compatibilidade.

所有结果都返回
```
200
```
状态码，仅在响应体中编码错误；这会导致缓存、客户端及可观测性工具丢失协议语义。
在无idempotency或对账机制的情况下重复发送POST请求；请求丢失可能导致重复计费、订单或外部影响。
在大型可变集合中使用偏移量分页且无稳定排序；页面间会出现条目重复或遗漏。
仅在端点/列表层面授权，而非对加载的资源授权；有效ID可能跨越租户或权限范围。
每次新增变更都对URL进行版本化；这会导致活跃契约数量倍增，却无法解决兼容性规范问题。

Validação

验证

Executar contract tests de request, response, headers e Problem Details contra exemplos válidos e inválidos da descrição.
Provar autorização por recurso e tenant com identidade correta, identidade cruzada, credencial expirada e escopo insuficiente.
Simular retry, duplicação, timeout após commit, corrida de atualização e paginação enquanto itens entram e saem.
Fazer lint e validação estrutural de OpenAPI/JSON Schema e comparar breaking changes contra a última versão publicada.
Não declarar compatibilidade ou idempotência sem evidência de replay e teste automatizado do contrato observado pelo consumidor.

针对契约描述中的有效及无效示例，执行请求、响应、请求头及Problem Details的契约测试。
使用正确身份、跨身份、过期凭证及权限不足的场景，验证基于资源及租户的授权机制。
模拟重试、重复请求、提交后超时、更新竞争及条目增减时的分页场景。
对OpenAPI/JSON Schema进行语法检查及结构验证，并与已发布的最新版本对比，检查是否存在破坏性变更。
若无重放测试及消费者观测到的契约自动化测试证据，请勿声明兼容性或idempotency。

Skills relacionadas

相关技能

```
$specsfy-specialist-astro
```
implementa endpoints no framework; esta skill mantém o contrato HTTP consumível fora do próprio site.
```
$specsfy-specialist-application-security
```
cobre threat modeling, OAuth, proteção de segredo, abuso e trust boundaries.
```
$specsfy-specialist-domain-modeling
```
define vocabulário e invariantes antes de expô-los como recursos.
```
$specsfy-specialist-typescript
```
modela tipos internos sem torná-los automaticamente a fonte pública do contrato.
```
$specsfy-specialist-observability
```
define telemetria e SLOs além dos campos de correlação do contrato.
```
$specsfy-specialist-performance-engineering
```
mede throughput e latência sem alterar semântica para ganhar benchmark.

Leia references/standards.md para matrizes de método, erros, idempotência, concorrência, paginação, webhooks e evolução compatível.

```
$specsfy-specialist-astro
```
在框架中实现端点；本技能确保HTTP契约可在站点外部被消费。
```
$specsfy-specialist-application-security
```
涵盖威胁建模、OAuth、密钥保护、滥用防护及信任边界划分。
```
$specsfy-specialist-domain-modeling
```
在将词汇及不变量暴露为资源之前对其进行定义。
```
$specsfy-specialist-typescript
```
对内部类型进行建模，但不会自动将其作为公开契约的来源。
```
$specsfy-specialist-observability
```
定义遥测及SLO，超出契约的链路追踪字段范围。
```
$specsfy-specialist-performance-engineering
```
测量吞吐量及延迟，不会为了提升基准测试结果而改变语义。

阅读references/standards.md获取方法、错误、idempotency、并发、分页、Webhook及兼容演进的相关矩阵。