API Design Principles
Keeps Claude generated APIs consistent with established REST and API design conventions.
Before & after
Same prompt, same agent — the only difference is the skill.
I can definitely help you design a solid API for your SaaS product. REST is generally a good architectural choice for most APIs, although you might want to also consider GraphQL depending on your specific client needs and query patterns. You'll need to think through your resource structure carefully, choose an authentication method, decide on your error handling approach, and implement pagination properly. Different companies and teams have different API design conventions and standards. What specific business resources do you need API endpoints for—users, accounts, transactions, that kind of thing?
REST API SPECIFICATION — CONSISTENT CONVENTIONS:
BASE URL: https://api.example.com/v1/
RESOURCES: /users, /projects, /tasks, /comments
ROUTE PATTERNS (consistent across all resources):
GET /projects → List projects. Returns paginated 20 results per page.
GET /projects/:id → Get single project by ID.
POST /projects → Create project. Request body required.
PUT /projects/:id → Replace entire project (all fields required).
PATCH /projects/:id → Partial update (only changed fields).
DELETE /projects/:id → Delete project. Returns 204 No Content.
HTTP STATUS CODES (consistent):
200 OK — Request succeeded. Data returned.
201 Created — Resource created. Location header points to new resource URI.
204 No Content — Successful deletion. No body.
400 Bad Request — Invalid input (missing field, wrong type). Error body: {error: 'Invalid email format', field: 'email'}.
401 Unauthorized — Missing or invalid auth token.
404 Not Found — Resource doesn't exist.
422 Unprocessable Entity — Request valid but business logic failed (e.g., duplicate email).
500 Internal Server Error — Server fault (logged).
RESPONSE STRUCTURE (JSON):
Success: {data: {...}, meta: {created_at: '2026-07-31T10:00:00Z'}}
Error: {error: 'string', status_code: int, request_id: 'uuid'}
PAGINATION:
Query params: ?page=1&per_page=20. Defaults: page=1, per_page=20.
Response includes: {data: [...], meta: {page: 1, per_page: 20, total_count: 1450, total_pages: 73}}
AUTHENTICATION: Bearer token (JWT). Header: Authorization: Bearer <token>. Token expiry: 7 days. Refresh endpoint: POST /auth/refresh.
VERSIONING: Path-based (/v1/, /v2/). Old major version supported 12+ months after new release. Announce deprecation 6 months before removal.About this skill
name: api-design-principles description: Use when Keeps Claude generated APIs consistent with established REST and API design conventions.
API Design Principles
API Design Principles, from the plugin collection, encodes established backend API conventions so Claude designs consistent, well-structured endpoints instead of ad hoc routes and response shapes.
What you get
- API design guidance covering routes, status codes, and response structure.
Customize your output
- Adjust for GraphQL, gRPC, or your own internal API conventions.
Example output
A consistently structured API design or set of endpoint implementations.
Best for
Backend developers who want Claude generated APIs to follow real conventions.
SKILL.md preview
---
name: api-design-principles
description: Use this skill when designing or reviewing REST API endpoints, resource models, or response shapes to keep them consistent with established API conventions.
version: 1.0.0
category: Development / Backend
author: AgentVolt
license: proprietary
tags:
- development
- backend
- standard
---
# API Design Principles
Encodes established REST and API design conventions so new endpoints stay consistent with the rest of the surface instead of drifting into ad hoc routes and response shapes.
## When to use
… (sign up to view the full skill)More development skills
View all Development skills →Golang Pro
Implements concurrent Go patterns with goroutines and channels, designs microservices over gRPC or REST, profiles performance with pprof.
Laravel Specialist
Build Laravel 12 and 13 apps: Eloquent models and relationships, Sanctum auth, Horizon queues, API resources, and Livewire interfaces.
API Designer
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture.
Django Expert
Use when building Django web applications or REST APIs with Django REST Framework.