# Designing Apis

Design APIs that are secure, scalable, and maintainable using RESTful, GraphQL, and...

- Repository: https://github.com/ancoleman/ai-design-components (526 stars)
- Category: Design
- License: MIT
- Last updated: 2025-12-11
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add ancoleman/ai-design-components --skill designing-apis -g -a claude-code -y`
Codex: `npx skills add ancoleman/ai-design-components --skill designing-apis -g -a codex -y`
Cursor: `npx skills add ancoleman/ai-design-components --skill designing-apis -g -a cursor -y`
Gemini CLI: `npx skills add ancoleman/ai-design-components --skill designing-apis -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add ancoleman/ai-design-components`

## Description

Design APIs that are secure, scalable, and maintainable using RESTful, GraphQL, and event-driven patterns. Use when designing new APIs, evolving existing APIs, or establishing API standards for teams.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Designing APIs

Design well-structured, scalable APIs using REST, GraphQL, or event-driven patterns. Focus on resource design, versioning, error handling, pagination, rate limiting, and security.

## When to Use This Skill

Use when:
- Designing a new REST, GraphQL, or event-driven API
- Establishing API design standards for a team or organization
- Choosing between REST, GraphQL, WebSockets, or message queues
- Planning API versioning and breaking change management
- Defining error response formats and HTTP status code usage
- Implementing pagination, filtering, and rate limiting patterns
- Designing OAuth2 flows or API key authentication
- Creating OpenAPI or AsyncAPI specifications

Do NOT use for:
- Implementation code (use `api-patterns` skill for Express, FastAPI code)
- Authentication implementation (use `auth-security` skill for JWT, sessions)
- API testing strategies (use `testing-strategies` skill)
- API deployment and infrastructure (use `deploying-applications` skill)

## Core Design Principles

### Resource-Oriented Design (REST)

Use nouns for resources, not verbs in URLs:
```
✓ GET    /users              List users
✓ GET    /users/123          Get user 123
✓ POST   /users              Create user
✓ PATCH  /users/123          Update user 123
✓ DELETE /users/123          Delete user 123

✗ GET    /getUsers
✗ POST   /createUser
```

Nest resources for relationships (limit depth to 2-3 levels):
```
✓ GET /users/123/posts
✓ GET /users/123/posts/456/comments
✗ GET /users/123/posts/456/comments/789/replies  (too deep)
```

For complete REST patterns, see references/rest-design.md

### HTTP Method Semantics

The rest: https://github.com/ancoleman/ai-design-components/blob/HEAD/skills/designing-apis/SKILL.md