Skills ZICQ category：Design api-design-principles

Api Design Principles

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.

31601 installs

Official URL：skills.sh

What this skill does

Intro in this page language first. The official description stays in its original wording; we do not rewrite SKILL.md.

What it does

Master REST and GraphQL API design principles to build intuitive, scalable, and maintainable APIs that delight developers

When to use it

This Skill

How agents load it

Per Agent Skills progressive disclosure: name and description load at startup (~100 tokens); the full SKILL.md body loads when the skill activates; scripts/, references/, and assets/ load only as needed. This file's sections: API Design Principles; When to Use This Skill; Core Concepts; 1. RESTful Design Principles; 2. GraphQL Design Principles; 3. API Versioning Strategies. It includes spec-recommended sections: input/output examples.

File analysis

File analysis: besides SKILL.md, the body references references/details.md. Those resources load on demand.

API Design PrinciplesWhen to Use This SkillCore Concepts1. RESTful Design Principles2. GraphQL Design Principles3. API Versioning StrategiesDetailed patterns and worked examplesBest PracticesREST APIsGraphQL APIsCommon Pitfalls

Source category：skills.sh agent-skill

Sources & links

Market sources：skills.sh

Full package on GitHub

OSS Skill ranking

SKILL.md & Agent activation

Official spec ↗

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.

DiscoverThe client exposes names and descriptions to the agent.
ActivateYour request or the task context selects the skill and loads its instructions.
Load resourcesReferenced scripts, documentation and assets are used when needed.

Files referenced by the instructions · 1

references/details.md

These paths are extracted from the text. Check the upstream package to verify the files exist.

Invocation syntax and available tools depend on your Agent client. Client integration guide ↗

Install this skill

Skills CLI ↗

Choose the target agent and installation scope, keep referenced package files, then verify the skill appears in the client's catalog.

This skill references supporting files. Retrieve the complete directory from the source; copying SKILL.md alone may leave missing dependencies.

Ask your Agent to install

Copy these instructions to a compatible agent and confirm the target directory matches your client.

Install the agent skill "api-design-principles" into my project. The full SKILL.md and official description are at https://zicq.com/en/skills/skl-242f155f9859274f-Api-Design-Principles.html
Save it as .cursor/skills/api-design-principles/SKILL.md or .claude/skills/api-design-principles/SKILL.md and keep the frontmatter name and description exactly as-is.
This skill also ships scripts/, references/, or assets/ — fetch the whole folder from https://github.com/wshobson/agents instead of creating only a SKILL.md.

Full package on GitHub ↗

Install from the terminal · Skills CLI

Requires Node.js and npx. First inspect the repository's skill list to confirm the name.

npx skills add 'https://github.com/wshobson/agents' --list

Target agent Installation scope

npx skills add 'https://github.com/wshobson/agents' --skill 'api-design-principles'

The CLI lets you choose the agent interactively. The default scope is the project; use -g for user scope. Confirm package availability with the discovery command, then use npx skills list to inspect installed skills.

SKILL.md source Copy freely; the source file is unchanged

---
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.

## When to Use This Skill

- 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)

## Core Concepts

### 1. RESTful Design Principles

**Resource-Oriented Architecture**

- Resources are nouns (users, orders, products), not verbs
- Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
- URLs represent resource hierarchies
- Consistent naming conventions

**HTTP Methods Semantics:**

- `GET`: Retrieve resources (idempotent, safe)
- `POST`: Create new resources
- `PUT`: Replace entire resource (idempotent)
- `PATCH`: Partial resource updates
- `DELETE`: Remove resources (idempotent)

### 2. GraphQL Design Principles

**Schema-First Development**

- Types define your domain model
- Queries for reading data
- Mutations for modifying data
- Subscriptions for real-time updates

**Query Structure:**

- Clients request exactly what they need
- Single endpoint, multiple operations
- Strongly typed schema
- Introspection built-in

### 3. API Versioning Strategies

**URL Versioning:**

```
/api/v1/users
/api/v2/users
```

**Header Versioning:**

```
Accept: application/vnd.api+json; version=1
```

**Query Parameter Versioning:**

```
/api/users?version=1
```

## Detailed patterns and worked examples

Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.

## Best Practices

### REST APIs

1. **Consistent Naming**: Use plural nouns for collections (`/users`, not `/user`)
2. **Stateless**: Each request contains all necessary information
3. **Use HTTP Status Codes Correctly**: 2xx success, 4xx client errors, 5xx server errors
4. **Version Your API**: Plan for breaking changes from day one
5. **Pagination**: Always paginate large collections
6. **Rate Limiting**: Protect your API with rate limits
7. **Documentation**: Use OpenAPI/Swagger for interactive docs

### GraphQL APIs

1. **Schema First**: Design schema before writing resolvers
2. **Avoid N+1**: Use DataLoaders for efficient data fetching
3. **Input Validation**: Validate at schema and resolver levels
4. **Error Handling**: Return structured errors in mutation payloads
5. **Pagination**: Use cursor-based pagination (Relay spec)
6. **Deprecation**: Use `@deprecated` directive for gradual migration
7. **Monitoring**: Track query complexity and execution time

## Common Pitfalls

- **Over-fetching/Under-fetching (REST)**: Fixed in GraphQL but requires DataLoaders
- **Breaking Changes**: Version APIs or use deprecation strategies
- **Inconsistent Error Formats**: Standardize error responses
- **Missing Rate Limits**: APIs without limits are vulnerable to abuse
- **Poor Documentation**: Undocumented APIs frustrate developers
- **Ignoring HTTP Semantics**: POST for idempotent operations breaks expectations
- **Tight Coupling**: API structure shouldn't mirror database schema

Found this skill helpful?

🚀 Share a Work Built With It

Readable layout

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.

When to Use This Skill

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)

Core Concepts

1. RESTful Design Principles

Resource-Oriented Architecture

Resources are nouns (users, orders, products), not verbs
Use HTTP methods for actions (GET, POST, PUT, PATCH, DELETE)
URLs represent resource hierarchies
Consistent naming conventions

HTTP Methods Semantics:

GET: Retrieve resources (idempotent, safe)
POST: Create new resources
PUT: Replace entire resource (idempotent)
PATCH: Partial resource updates
DELETE: Remove resources (idempotent)

2. GraphQL Design Principles

Schema-First Development

Types define your domain model
Queries for reading data
Mutations for modifying data
Subscriptions for real-time updates

Query Structure:

Clients request exactly what they need
Single endpoint, multiple operations
Strongly typed schema
Introspection built-in

3. API Versioning Strategies

URL Versioning:

/api/v1/users
/api/v2/users

Header Versioning:

Accept: application/vnd.api+json; version=1

Query Parameter Versioning:

/api/users?version=1

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

Best Practices

REST APIs

Consistent Naming: Use plural nouns for collections (/users, not /user)
Stateless: Each request contains all necessary information
Use HTTP Status Codes Correctly: 2xx success, 4xx client errors, 5xx server errors
Version Your API: Plan for breaking changes from day one
Pagination: Always paginate large collections
Rate Limiting: Protect your API with rate limits
Documentation: Use OpenAPI/Swagger for interactive docs

GraphQL APIs

Schema First: Design schema before writing resolvers
Avoid N+1: Use DataLoaders for efficient data fetching
Input Validation: Validate at schema and resolver levels
Error Handling: Return structured errors in mutation payloads
Pagination: Use cursor-based pagination (Relay spec)
Deprecation: Use @deprecated directive for gradual migration
Monitoring: Track query complexity and execution time

Common Pitfalls

Over-fetching/Under-fetching (REST): Fixed in GraphQL but requires DataLoaders
Breaking Changes: Version APIs or use deprecation strategies
Inconsistent Error Formats: Standardize error responses
Missing Rate Limits: APIs without limits are vulnerable to abuse
Poor Documentation: Undocumented APIs frustrate developers
Ignoring HTTP Semantics: POST for idempotent operations breaks expectations
Tight Coupling: API structure shouldn't mirror database schema

Related skills

Design