home / skills / dasien / claudemultiagenttemplate / api-design

api-design skill

safe

This skill helps design clear RESTful APIs with proper resource modeling, error handling, and contracts that teams can consistently implement.

npx playbooks add skill dasien/claudemultiagenttemplate --skill api-design

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

Files (1)

SKILL.md

1.5 KB

---
name: "API Design"
description: "Design RESTful APIs with proper resource modeling, HTTP methods, error handling, and clear contracts following REST principles"
category: "architecture"
required_tools: ["Read", "Write", "WebSearch"]
---

# API Design

## Purpose
Design clear, consistent, and maintainable REST APIs following industry best practices and conventions.

## When to Use
- Designing new API endpoints
- Refactoring existing APIs
- Creating integration interfaces
- Planning service-to-service communication

## Key Capabilities
1. **REST Principles** - Apply RESTful design patterns correctly
2. **Resource Modeling** - Design clear resource hierarchies
3. **Error Responses** - Define consistent error handling

## Approach
1. Identify resources and their relationships
2. Design URL structure (nouns, not verbs)
3. Choose appropriate HTTP methods (GET, POST, PUT, DELETE)
4. Design request/response formats
5. Plan error handling and status codes
6. Document with examples

## Example
**Context**: User profile management API

**Design**:
````
GET    /users/{id}           # Get user
POST   /users                # Create user
PUT    /users/{id}           # Update user
DELETE /users/{id}           # Delete user
GET    /users/{id}/profile   # Get profile
PUT    /users/{id}/profile   # Update profile
````

## Best Practices
- ✅ Use nouns for resources, HTTP verbs for actions
- ✅ Consistent URL patterns and naming
- ✅ Proper HTTP status codes (200, 201, 404, 500)
- ❌ Avoid: Verbs in URLs (/getUser, /createUser)

Overview

This skill designs clear, consistent, and maintainable RESTful APIs using resource-oriented modeling and standard HTTP semantics. It focuses on predictable URL structures, correct method usage, and robust error contracts to make integrations reliable and easy to consume. The outcome is an API surface that is intuitive for clients and simple to evolve.

How this skill works

I identify domain resources and their relationships, then map them to noun-based URL paths and appropriate HTTP methods. I define request and response schemas, choose status codes for success and failure, and specify consistent error payloads. Finally, I create concise examples and rules that developers can follow when implementing or extending the API.

When to use it

Designing new public or internal REST endpoints
Refactoring inconsistent or hard-to-use APIs
Defining service-to-service interfaces and contracts
Preparing API documentation and examples
Standardizing error handling across services

Best practices

Model resources as nouns and reflect hierarchy in paths (e.g., /orders/{id}/items)
Use the correct HTTP method semantics: GET for read, POST for create, PUT/PATCH for update, DELETE for remove
Return proper status codes (200, 201, 204, 400, 404, 409, 500) and avoid overloading 200 for errors
Design consistent error response format with machine-readable error codes and human messages
Version APIs explicitly (e.g., /v1/) and avoid breaking changes without a migration plan

Example use cases

User management: /users, /users/{id}, /users/{id}/profile with proper create/read/update/delete operations
E-commerce orders: /orders, /orders/{id}, /orders/{id}/items to model ownership and actions
Integration gateway: stable contracts for service-to-service calls with documented request/response schemas
Refactor legacy endpoints that use verbs in paths into resource-oriented routes with clear status codes

FAQ

How do I choose between PUT and PATCH?

Use PUT for full resource replacement and PATCH for partial updates. Prefer PATCH when clients will send only changed fields to reduce payload size.

What should an error response include?

Include an HTTP status code, a machine-readable error code, a short human message, and optional details or links for remediation. Keep the structure consistent across endpoints.