360 Secure SkillHub
360 安全技能中心

Rest Best Practices

该 Skill 提供 REST 深度工作流，围绕资源建模、HTTP 方法与安全性、状态码与错误、分页与过滤、缓存与条件请求、版本化与演进六个阶段给出设计指导和最终检查清单，并提示幂等键等实践，适用于设计 HTTP API 或评审控制器与网关。

mike47512
mike47512
热度 47.10
最近更新 2026-05-11 17:36:03
分类：开发依赖：纯提示词应用场景：API 集成 / 代码审查 / 工作流

安装技能

复制下面的话术发给你的 Agent，它会通过 secure-skills 检索并安装该技能。

执行命令安装此 skill： npx secure-skills-cli add rest-best-practices
Metadata
name
rest-best-practices
description
Deep REST workflow—resource modeling, HTTP methods and safety, status codes, errors, pagination, caching, versioning, and idempotency. Use when designing HTTP APIs or reviewing controllers and gateways.

REST Best Practices (Deep Workflow)

REST is HTTP semantics used consistently: resources as nouns, methods with meaning, predictable errors, and cacheable reads where safe.

When to Offer This Workflow

Trigger conditions:

  • Designing public or partner HTTP APIs
  • Inconsistent verbs (GET with side effects); wrong status codes
  • CDN/caching surprises; client retry storms on POST

Initial offer:

Use six stages: (1) resource model, (2) methods & safety, (3) status & errors, (4) pagination & filtering, (5) caching & conditional requests, (6) versioning & evolution). Confirm JSON conventions and authentication model.

Stage 1: Resource Model

Goal: Clear collection vs item resources; relationships via sub-paths or hypermedia links (HATEOAS optional).

Exit condition: Table or diagram of resources, identifiers, and canonical URLs.

Stage 2: Methods & Safety

Goal: GET/HEAD safe and idempotent; POST for creation or non-idempotent actions; PUT replaces; PATCH partial; DELETE removes.

Anti-patterns

  • Non-idempotent GET; overloaded POST for everything without documented patterns

Stage 3: Status & Errors

Goal: Correct 4xx vs 5xx; consistent error body (e.g., RFC 7807 Problem Details) with stable type codes and optional instance for support.

Stage 4: Pagination & Filtering

Goal: Cursor pagination for large lists; document sort/filter query params; cap page sizes.

Stage 5: Caching & Conditional Requests

Goal: ETag/Last-Modified for cacheable GET; Cache-Control directives; validate with intermediaries (CDN) when used.

Stage 6: Versioning & Evolution

Goal: URL prefix or header versioning; deprecation policy; Idempotency-Key on POST when clients retry.

Final Review Checklist

  • Resource model clear and consistent
  • HTTP methods match semantics; GET is safe
  • Status codes and errors consistent
  • Pagination and filtering documented
  • Caching headers where appropriate
  • Versioning and idempotency strategy

Tips for Effective Guidance

  • Not everything is CRUD—model commands as sub-resources or task resources explicitly.
  • Pair with openapi-spec for contract-first workflows.

Handling Deviations

  • Internal APIs still benefit from the same discipline—future consumers are often external.