api-design

Solid

REST API contract designer and reviewer. ALWAYS use when designing new endpoints, reviewing existing API contracts, planning API versioning, or standardizing error models. Covers resource modeling (URL/naming), HTTP method semantics, status code selection, error model consistency, pagination/filtering/sorting, idempotency keys, concurrency control (ETag/If-Match), object-level authorization (IDOR prevention), rate limiting, backward compatibility assessment, and OpenAPI-ready output. Use even for "just add an endpoint" — inconsistent APIs compound into integration nightmares that are extremely expensive to fix after clients depend on them.

AI & Automation 30 stars 5 forks Updated yesterday MIT

Install

View on GitHub

Quality Score: 82/100

Stars 20%

Recency 20%

100

Frontmatter 20%

Documentation 15%

100

Issue Health 10%

License 10%

100

Description 5%

100

Skill Content

# REST API Design Review ## Quick Reference | If you need to… | Go to | |----------------------------------------|------------------------------------------| | Understand what this skill covers | §1 Scope | | Check mandatory prerequisites | §2 Mandatory Gates | | Choose review depth | §3 Depth Selection | | Handle incomplete context | §4 Degradation Modes | | Evaluate API design item by item | §5 Design Checklist | | Avoid common API design mistakes | §6 Anti-Examples | | Score the review result | §7 Scorecard | | Format review output | §8 Output Contract | | Deep-dive error model patterns | `references/error-model-patterns.md` | | Check compatibility rules | `references/compatibility-rules.md` | --- ## §1 Scope **In scope** — REST API contract design and review: - Resource modeling (URL structure, naming, hierarchy) - HTTP method semantics (GET/POST/PUT/PATCH/DELETE) - Status code selection (2xx/4xx/5xx semantic correctness) - Error model design (machine-parseable codes, field-level details) - Pagination, filtering, sorting, search patterns - Idempotency (Idempotency-Key header, retry safety) - Concurrency...

Details

Author: johnqtcg
Repository: johnqtcg/awesome-skills
Created: 6 months ago
Last Updated: yesterday
Language: Python
License: MIT

Integrates with

Anthropic · AI REST API · API

Similar Skills

Semantically similar based on skill content — not just same category

API & Backend Listed

api-design-review

Review an API contract (REST or GraphQL) before or while it is implemented, checking resource naming, HTTP semantics, status codes, error shape, pagination, versioning, idempotency, and backward compatibility, and producing concrete revisions rather than abstract advice. Use when designing new endpoints, changing an existing API's surface, or reviewing a PR that adds or modifies API routes.

5 Updated 3 days ago

KhaledSaeed18

API & Backend Listed

api-design

Review or design REST and GraphQL APIs for correctness, consistency, and evolvability. Always use this skill when designing a new API, reviewing an existing one, choosing HTTP verbs, designing URL structure, defining error response shapes, thinking through versioning, or writing OpenAPI/Swagger specs. Use when the user says "review this API", "how should I model this resource", "is this endpoint design right", "should I use PUT or PATCH", "is this breaking", or "how should errors look". Use even when the question seems simple.

1 Updated 2 days ago

AllThingsSmitty