API Designer

Expert in designing REST and GraphQL APIs that are robust, scalable, and maintainable.

When This Skill Activates

Activates when you:

• •Design a new API
• •Review API design
• •Improve existing API
• •Create API specifications

REST API Design Principles

1. Resource-Oriented Design

Good:

GET    /users          # List users
POST   /users          # Create user
GET    /users/{id}     # Get specific user
PATCH  /users/{id}     # Update user
DELETE /users/{id}     # Delete user

Avoid:

POST   /getUsers       # Should be GET
POST   /users/create  # Redundant
GET    /users/get/{id} # Redundant

2. HTTP Methods

3. Status Codes

4. Naming Conventions

• •URLs: kebab-case (/user-preferences)
• •JSON: camelCase ({"userId": "123"})
• •Query params: snake_case or camelCase (?page_size=10)

5. Pagination

GET /users?page=1&page_size=20

Response:
{
  "data": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 100,
    "total_pages": 5
  }
}

6. Filtering and Sorting

GET /users?status=active&sort=-created_at,name

# -created_at = descending
# name = ascending

GraphQL API Design

Schema Design

type Query {
  user(id: ID!): User
  users(limit: Int, offset: Int): UserConnection!
}

type Mutation {
  createUser(input: CreateUserInput!): CreateUserPayload!
  updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
}

type User {
  id: ID!
  email: String!
  profile: Profile
  posts(first: Int, after: String): PostConnection!
}

type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

Best Practices

• •Nullability: Default to non-null, nullable only when appropriate
• •Connections: Use cursor-based pagination for lists
• •Payloads: Use mutation payloads for consistent error handling
• •Descriptions: Document all types and fields

API Versioning

Approaches

URL Versioning (Recommended):

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

Header Versioning:

GET /users
Accept: application/vnd.myapi.v2+json

Versioning Guidelines

• •Start with v1
• •Maintain backwards compatibility when possible
• •Deprecate old versions with notice
• •Document breaking changes

Authentication & Authorization

Authentication Methods

1. •JWT Bearer Token

Authorization: Bearer <token>

1. •API Key

X-API-Key: <key>

1. •OAuth 2.0

Authorization: Bearer <access_token>

Authorization

• •Use roles/permissions
• •Document required permissions per endpoint
• •Return 403 for authorization failures

Rate Limiting

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1631234567

Recommended limits:

• •Public APIs: 100-1000 requests/hour
• •Authenticated APIs: 1000-10000 requests/hour
• •Webhooks: 10-100 requests/minute

Documentation Requirements

• •All endpoints documented
• •Request/response examples
• •Authentication requirements
• •Error response formats
• •Rate limits
• •SDK examples (if available)

Scripts

Generate API scaffold:

python scripts/generate_api.py <resource-name>

Validate API design:

python scripts/validate_api.py openapi.yaml

References

• •references/rest-patterns.md - REST design patterns
• •references/graphql-patterns.md - GraphQL design patterns
• •REST API Tutorial
• •GraphQL Best Practices