Skip to content

Releases: psenger/Best-Practices-For-Rest-API

v2.0.0 — Major content expansion

22 Mar 12:32
@psenger psenger
v2.0.0
26c4805
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Choose a tag to compare

View all tags
v2.0.0 — Major content expansion Latest
Latest

What's New in v2.0.0

This release is a major content expansion, aligning the knowledge base with the review-api-design Skill 2.0 — which was distilled from this repo and has since grown significantly.

Tip

This knowledge base now powers a Skill 2.0 compatible with any LLM that supports the standard. Install it and get structured, severity-tagged API design reviews:

npx skills add psenger/ai-agent-skills --skill review-api-design

Security (docs/03-security.md)

  • BOLA (Broken Object Level Authorization) — OWASP API1:2023
  • PKCE mandatory per RFC 9700 / OAuth 2.1
  • Passkeys/FIDO2 as MFA gold standard per NIST SP 800-63-4; SMS downgraded
  • DPoP (RFC 9449) for token binding
  • BFF (Backend-for-Frontend) pattern for SPAs
  • Step-up authentication (RFC 9470)
  • Enumeration attack prevention (consistent responses, opaque IDs, rate limiting)
  • Information disclosure prevention (suppress stack traces, strip server headers)
  • CSRF protections (SameSite cookies, Fetch Metadata headers, anti-CSRF tokens)
  • Security headers (HSTS, CSP, X-Content-Type-Options)
  • OWASP API Security Top 10 (2023) full checklist
  • Security logging and monitoring

API Communication Patterns (docs/07-api-communication-patterns.md)

  • Renamed from 07-graphql-vs-rest.md — expanded to cover all four patterns
  • WebSockets — bidirectional, strengths/weaknesses, design checklist
  • SSE (Server-Sent Events) — unidirectional, auto-reconnect, HTTP/2 multiplexing
  • Comparison matrix (REST vs GraphQL vs WebSockets vs SSE)
  • Decision guide for all four patterns
  • Hybrid architecture patterns (REST+SSE, REST+WS, REST+GraphQL, GraphQL+Subscriptions)
  • Anti-patterns and red flags

New: Design Extensibility (docs/10-design-extensibility.md)

  • Fixed vs variable arity
  • Metadata extension points (Stripe, AWS, Slack patterns)
  • Response evolution — what's safe vs breaking
  • SOLID principles applied to APIs
  • Postel's Law and Hyrum's Law

New: Sources and Further Reading (docs/11-sources.md)

  • 70+ curated references organised by category

Resilience (docs/05-resilience.md)

  • SLIs, SLOs, and error budgets
  • RED metrics (Rate, Errors, Duration)
  • Structured logging
  • Distributed tracing (OpenTelemetry, W3C Trace Context)
  • Alerting strategy

Contributing

  • CONTRIBUTING.md — writing tone, citation format, markdown conventions, chapter structure guide
  • .github/PULL_REQUEST_TEMPLATE.md
  • .github/ISSUE_TEMPLATE/content-suggestion.md
  • .github/ISSUE_TEMPLATE/correction.md
Assets 2
Loading