home / skills / sickn33 / antigravity-awesome-skills / api-design-principles

api-design-principles skill

This skill guides REST and GraphQL API design to create intuitive, scalable, and maintainable interfaces with clear versioning and documentation.

This is most likely a fork of the api-design-principles skill from nilecui

npx playbooks add skill sickn33/antigravity-awesome-skills --skill api-design-principles

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

Files (6)

SKILL.md

1.5 KB

---
name: api-design-principles
description: Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers. Use when designing new APIs, reviewing API specifications, or establishing API design standards.
---

# API Design Principles

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers and stand the test of time.

## Use this skill when

- Designing new REST or GraphQL APIs
- Refactoring existing APIs for better usability
- Establishing API design standards for your team
- Reviewing API specifications before implementation
- Migrating between API paradigms (REST to GraphQL, etc.)
- Creating developer-friendly API documentation
- Optimizing APIs for specific use cases (mobile, third-party integrations)

## Do not use this skill when

- You only need implementation guidance for a specific framework
- You are doing infrastructure-only work without API contracts
- You cannot change or version public interfaces

## Instructions

1. Define consumers, use cases, and constraints.
2. Choose API style and model resources or types.
3. Specify errors, versioning, pagination, and auth strategy.
4. Validate with examples and review for consistency.

Refer to `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

## Resources

- `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

Overview

This skill teaches REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that developers enjoy using. It focuses on practical patterns for resource modeling, error design, versioning, pagination, and authentication. Use it to guide API decisions, reviews, and team standards so your interfaces remain predictable and future-proof.

How this skill works

The skill walks through a four-step design workflow: define consumers and constraints, choose an API style and model resources or types, specify cross-cutting concerns (errors, auth, versioning, pagination), and validate with examples and reviews. It provides concrete guidelines and checklists you can apply to new designs, refactors, or migration plans between REST and GraphQL. Outputs include standardized contracts, examples, and a checklist for consistency and review.

When to use it

Designing a new REST or GraphQL API from scratch
Refactoring an existing API to improve usability or scalability
Establishing API design standards and team conventions
Reviewing API specifications before implementation or release
Planning a migration between API paradigms (REST ↔ GraphQL)
Creating developer-facing API documentation and examples

Best practices

Start with consumers: list primary use cases, clients, and constraints before modeling resources
Prefer consistent naming, predictable URL/resource structures, and standard HTTP semantics for REST
For GraphQL, model types for clear ownership and avoid overly chatty schemas; favor explicit mutations
Define error formats, status codes, and retry semantics up front and document them
Standardize auth, rate limiting, pagination, and versioning strategies across APIs
Validate designs with example requests/responses and a short review checklist before implementation

Example use cases

Drafting an API contract for a new mobile-first backend with constrained bandwidth
Refactoring a public REST API to reduce breaking changes and adopt semantic versioning
Designing a GraphQL schema for a dashboard product while preventing N+1 query issues
Creating an API review checklist to onboard new engineers to team standards
Planning a phased migration from REST endpoints to a GraphQL gateway

FAQ

When should I choose REST over GraphQL?

Choose REST for simple, resource-oriented APIs with strong caching requirements or when predictable HTTP semantics are important; choose GraphQL when clients need flexible, aggregated queries and a single endpoint suits your client needs.

How do I minimize breaking changes?

Use versioning strategies, add fields instead of removing them, deprecate explicitly with timelines, and maintain backward-compatible contracts while communicating changes to consumers.