playbooks

home / skills / sandraschi / advanced-memory-mcp / api-design-architect

api-design-architect skill

/skills/technical/api-design-architect

This skill helps you design scalable, secure REST and GraphQL APIs by applying best-practice guidelines across structure, security, and governance.

npx playbooks add skill sandraschi/advanced-memory-mcp --skill api-design-architect

Review the files below or copy the command above to add this skill to your agents.

Files (9)
SKILL.md
2.0 KB
---
name: api-design-architect
description: RESTful and GraphQL API design expert covering best practices, security, and scalability
license: Proprietary
---

# API Design Architect
> **Status**: ✅ Research complete
> **Last validated**: 2025-11-08
> **Confidence**: 🟡 Medium — Research-backed playbook – refresh quarterly

## How to use this skill
1. Skim [modules/core-guidance.md](modules/core-guidance.md) for framing and triage cues.
2. Load protocol-specific patterns from [modules/design-foundations.md](modules/design-foundations.md).
3. Use [modules/lifecycle-and-governance.md](modules/lifecycle-and-governance.md) to plan change management and documentation.
4. Apply [modules/security-and-observability.md](modules/security-and-observability.md) before launch.
5. Revisit [modules/known-gaps.md](modules/known-gaps.md) each quarter and log findings in the [modules/research-checklist.md](modules/research-checklist.md).

## Module overview
- [Core guidance](modules/core-guidance.md) — decision tree, API style selection, stakeholder prompts.
- [Design foundations](modules/design-foundations.md) — REST, GraphQL, gRPC, and event-driven design blueprints.
- [Lifecycle & governance](modules/lifecycle-and-governance.md) — versioning, review ceremonies, documentation, consumability.
- [Security & observability](modules/security-and-observability.md) — authn/z, rate limiting, threat modelling, telemetry.
- [Known gaps](modules/known-gaps.md) — research debt and upcoming RFCs to review.
- [Research checklist](modules/research-checklist.md) — renewal workflow with links to canonical sources.

## Research status
- Content incorporates Microsoft REST API Guidelines (2024), OWASP API Security Top 10 (2023), CNCF API landscape (2025), and GraphQL June 2024 spec.
- Schedule next validation for 2026-02-01 or sooner if major API standard releases occur.
- Known gaps call out AsyncAPI 3.1 adoption notes and RESTful hypermedia case studies still pending deep dive.

Overview

This skill is an API design and architecture playbook focused on RESTful and GraphQL services, with practical guidance on security, observability, and scalability. It synthesizes industry standards and provides a decision-driven approach to choose styles, define contracts, and plan lifecycle governance. The content is research-backed and intended for architects, platform teams, and engineering leads.

How this skill works

The skill guides you through selecting an API style based on use cases and constraints, then applies protocol-specific patterns for REST and GraphQL. It includes lifecycle steps for versioning, reviews, and documentation, and enforces security and observability checks before launch. Known gaps and a quarterly research checklist keep the guidance current and auditable.

When to use it

  • When choosing between REST, GraphQL, gRPC, or event-driven APIs during design kickoff
  • During security threat modeling and pre-launch readiness reviews
  • When defining versioning, deprecation, and governance processes for public or internal APIs
  • For scalability planning, rate-limiting strategy, and telemetry design
  • When auditing an existing API for consumability, consistency, or migration needs

Best practices

  • Select API style by client needs and data access patterns; document the decision and trade-offs
  • Use consistent error and pagination formats, plus clear resource naming and schema contracts
  • Enforce authn/z, input validation, and OWASP API Security mitigations early in design
  • Design telemetry and SLIs from day one: request traces, error budgets, and usage metrics
  • Implement versioning and deprecation policies with a documented lifecycle and review cadence

Example use cases

  • Designing a new public REST API with standard error formats, rate limits, and SDK-friendly contracts
  • Adopting GraphQL for flexible client-driven queries while enforcing field-level auth and cost limits
  • Conducting a security and observability readiness review before a major API launch
  • Defining API governance, versioning rules, and a change-review workflow for platform teams
  • Planning a migration strategy from monolithic endpoints to event-driven or gRPC backends

FAQ

When should I choose GraphQL over REST?

Choose GraphQL when clients need flexible, precise data shapes and you can manage query cost and field-level authorization; prefer REST for simple resource-centric interactions and wide HTTP tooling compatibility.

How often should the guidance be reviewed?

Review quarterly or sooner when major API standards or security advisories are released; maintain a checklist for research updates and known gaps.