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

Method

Safe

Idempotent

Purpose

GET

✓

✓

Read resource

POST

✗

✗

Create resource

PUT

✗

✓

Replace resource

PATCH

✗

✗

Update resource

DELETE

✗

✓

Delete resource

3. Status Codes

Code

Meaning

Usage

200

OK

Successful GET, PATCH, DELETE

201

Created

Successful POST

204

No Content

Successful DELETE with no body

400

Bad Request

Invalid input

401

Unauthorized

Missing or invalid auth

403

Forbidden

Authenticated but not authorized

404

Not Found

Resource doesn't exist

409

Conflict

Resource already exists

422

Unprocessable

Valid syntax but semantic errors

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error

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

• JWT Bearer Token

Authorization: Bearer <token>

• API Key

X-API-Key: <key>

• 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