api-design
/api-design
Guidelines for designing RESTful APIs and TypeScript interfaces. Use when designing new endpoints, reviewing API contracts, or structuring data models.
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 05.07.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Guidelines for designing RESTful APIs and TypeScript interfaces. Use when designing new endpoints, reviewing API contracts, or structuring data models.
Original author description
Guidelines for designing RESTful APIs and TypeScript interfaces. Use when designing new endpoints, reviewing API contracts, or structuring data models.
How it works
- Overview
- REST Endpoint Design
- Response Formats
- TypeScript Interface Design
- Pagination
- Versioning
- Common Patterns
- Security Considerations
SKILL.md preview
---
name: api-design
description: Guidelines for designing RESTful APIs and TypeScript interfaces. Use when designing new endpoints, reviewing API contracts, or structuring data models.
license: MIT
---
# API Design Guidelines
## Overview
This skill provides guidelines for designing clean, consistent APIs. Apply these patterns when creating new endpoints, defining TypeScript interfaces, or reviewing API contracts.
**Keywords**: API design, REST, endpoints, TypeScript interfaces, data modeling, HTTP methods, response formats
## REST Endpoint Design
### URL Structure
```
/{resource} # Collection
/{resource}/{id} # Single resource
/{resource}/{id}/{sub-resource} # Nested resource
```
**Good examples:**
- `GET /users` - List users
- `GET /users/123` - Get user 123
- `POST /users/123/orders` - Create order for user 123
**Avoid:**
- `/getUsers` - Don't use verbs in URLs
- `/user/list` - Don't use action words
- `/users/123/getOrders` - HTTP method implies action
### HTTP Methods
| Method | Purpose | Idempotent | Body |
| ------ | ---------------- | ---------- | ---- |
| GET | Read resource | Yes | No |
| POST | Create resource | No | Yes |
| PUT | Replace resource | Yes | Yes |
| PATCH | Update resource | No | Yes |
| DELETE | Remove resource | Yes | No |
### Response Codes
**Success:**
- `200` - OK (GET, PUT, PATCH with body)
- `201` - Created (POST)
- `204` - No Content (DELETE, PUT/PATCH without body)
**Client errors:**
- `400` - Bad Request (validation failed)
- `401` - Unauthorized (no/invalid auth)
- `403` - Forbidden (no permission)
- `404` - Not Found
- `409` - Conflict (duplicate, state conflict)
- `422` - Unprocessable Entity (semantic errors)
**Server errors:**
- `500` - Internal Server Error
- `503` - Service Unavailable
## Response Formats
### Success Response
```typescript
// Single resource
{
"data": {
"id": "123",
"name": "Example",
"createdAt": "2024-01-15T10:30:00Z"
}
}
// Collection
{
"data": [...],
"meta": {
"total": 100,
"page": 1,
"pageSize": 20
}
}
```
### Error Response
```typescript
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"details": [
{
"field": "email",
"message": "Invalid email format"
}
]
}
}
```
## TypeScript Interface Design
### Naming Conventions
```typescript
// Entities use PascalCase nouns
interface User {}
interface OrderItem {}
// Request/Response types include suffix
interface CreateUserRequest {}
interface GetUserResponse {}
// Params types for function arguments
interface ListUsersParams {}
```
### Required vs Optional
```typescript
// Required fields: always present
interface User {
id: string;
email: string;
createdAt: Date;
}
// Optional fields: may be undefined
interface CreateUserRequest {
email: string;
name?: string; // Optional
metadata?: Record<string, unknown>;
}
```
### Discriminated Unions
Use for type-safe variants:
```typescript
type PaymentMethod =
| { type: 'card'; cardNumber: string; expiry: string }
| { type: 'bank'; accountNumber: string; routingNumber: string }
| { type: 'crypto'; walletAddress: string };
// Usage
function processPayment(method: PaymentMethod) {
switch (method.type) {
case 'card':
// TypeScript knows cardNumber exists
return chargeCard(method.cardNumber);
case 'bank':
return initiateTransfer(method.accountNumber);
case 'crypto':
return sendCrypto(method.walletAddress);
}
}
```
## Pagination
### Offset-based (Simple)
```typescript
interface PaginationParams {
page?: number; // Default: 1
pageSize?: number; // Default: 20, max: 100
}
interface PaginatedResponse<T> {
data: T[];
meta: {
page: number;
pageSize: number;
total: number;
totalPages: number;
};
}
```
### Cursor-based (Scalable)
```typescript
interface CursorParams {
cursor?: string;
limit?: number;
}
interface CursorResponse<T> {
data: T[];
meta: {
nextCursor: string | null;
hasMore: boolean;
};
}
```
## Versioning
### URL Versioning (Recommended)
```
/api/v1/users
/api/v2/users
```
### Header Versioning
```
Accept: application/vnd.api+json; version=2
```
## Common Patterns
### Filtering
```
GET /users?status=active&role=admin
GET /orders?createdAfter=2024-01-01&createdBefore=2024-02-01
```
### Sorting
```
GET /users?sort=createdAt:desc
GET /users?sort=lastName:asc,firstName:asc
```
### Field Selection
```
GET /users?fields=id,name,email
GET /users/123?include=orders,profile
```
## Security Considerations
1. **Authentication** - Use Bearer tokens in Authorization header
2. **Rate limiting** - Include `X-RateLimit-*` headers
3. **Input validation** - Validate all request bodies with schemas
4. **Output encoding** - Escape HTML in responses if rendered
5. **CORS** - Configure allowed origins explicitly
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · zjunlp/skills | 100 | MIT |
| proyecto26/system-design-skills | 100 | MIT |
| ericrisco/rsc-harness | 100 | MIT |
| Sanit-mann/The-Insectoids | 100 | MIT |
| yonatangross/orchestkit | 100 | MIT |
| travisjneuman/.claude | 100 | MIT |
| wrongstack/wrongstack | 100 | MIT |
| jelvodev/yaap | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version e15b4f1dbcd5 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100api
RESTful API design patterns and best practices. Use when creating endpoints, designing APIs, or implementing routes. - 100api-design-patterns
RESTful API design, error handling, versioning, and best practices. Use when designing APIs, reviewing endpoints, implementing error responses, or setting up API structure. Triggers on "design API", "review API", "REST best practices", or "API patterns". - 95rest-api-designer
Design RESTful API endpoints with proper resource modeling, HTTP methods, and URL structure. Use when creating REST APIs, designing endpoints, or structuring API resources. - 100api-design-patterns
Design RESTful APIs with pagination, filtering, and OpenAPI docs. Use for FastAPI endpoint design. - 100restful-api-design-best-practices
Use this skill when designing, reviewing, or standardizing RESTful HTTP APIs adhering to strict resource modeling, status codes, and JSON conventions. - 100rest-api-design
Designs RESTful APIs with proper resource naming, HTTP methods, status codes, and response formats. Use when building new APIs, establishing API conventions, or designing developer-friendly interfaces.