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 27 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: 4 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.

4 Updated today

KhaledSaeed18

API & Backend Solid

api-design

Use when designing or reviewing an HTTP API. Covers resource modeling, status codes, pagination, idempotency, versioning, error formats, and the contract details that break clients when you get them wrong.

23 Updated yesterday

nimadorostkar

API & Backend Listed

api-design

REST/HTTP API design patterns — resource naming, status codes, pagination, filtering, errors, versioning, idempotency. Use when designing or reviewing API endpoints.

15 Updated today

jedbjorn