home / skills / yonatangross / orchestkit / api-design-framework

api-design-framework skill

safe

/plugins/ork/skills/api-design-framework

This skill guides you to design robust REST, GraphQL, and gRPC APIs with consistent conventions, versioning, pagination, and secure patterns.

npx playbooks add skill yonatangross/orchestkit --skill api-design-framework

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

Files (11)

SKILL.md

8.4 KB

---
name: api-design-framework
description: Comprehensive API design patterns for REST, GraphQL, and gRPC. Use when designing APIs, creating endpoints, adding routes, implementing pagination, rate limiting, or authentication patterns.
context: fork
agent: backend-system-architect
version: 1.2.0
author: AI Agent Hub
tags: [api, rest, graphql, grpc, backend, documentation]
user-invocable: false
---

# API Design Framework

This skill provides comprehensive guidance for designing robust, scalable, and developer-friendly APIs. Whether building REST, GraphQL, or gRPC services, this framework ensures consistency, usability, and maintainability.

## Overview
- Designing new API endpoints or services
- Establishing API conventions for a team or organization
- Reviewing API designs for consistency and best practices
- Migrating or versioning existing APIs
- Creating API documentation (OpenAPI, AsyncAPI)
- Choosing between REST, GraphQL, or gRPC

## API Design Principles

### 1. Developer Experience First
APIs should be intuitive and self-documenting:
- Clear, consistent naming conventions
- Predictable behavior and responses
- Comprehensive documentation
- Helpful error messages

### 2. Consistency Over Cleverness
Follow established patterns rather than inventing new ones:
- Standard HTTP methods and status codes (REST)
- Conventional query structures (GraphQL)
- Idiomatic proto definitions (gRPC)

### 3. Evolution Without Breaking Changes
Design for change from day one:
- API versioning strategy
- Backward compatibility considerations
- Deprecation policies
- Migration paths

### 4. Performance by Design
Consider performance implications:
- Pagination for large datasets
- Filtering and partial responses
- Caching strategies
- Rate limiting

---

## Bundled Resources

- `assets/openapi-template.yaml` - OpenAPI 3.1 specification template
- `assets/asyncapi-template.yaml` - AsyncAPI specification template
- `references/rest-api.md` - REST API design patterns
- `references/graphql-api.md` - GraphQL API design patterns
- `references/grpc-api.md` - gRPC API design patterns
- `references/frontend-integration.md` - Frontend API integration patterns

---

## Protocol References

### REST API Design
**See: `references/rest-api.md`**

Key topics covered:
- Resource naming conventions (plural nouns, hierarchical relationships)
- HTTP methods (GET, POST, PUT, PATCH, DELETE)
- Status codes (2xx, 4xx, 5xx)
- Request/response formats
- Pagination (cursor-based vs offset-based)
- Filtering, sorting, field selection
- API versioning strategies
- Rate limiting headers
- Authentication patterns (Bearer, API Key)

### GraphQL API Design
**See: `references/graphql-api.md`**

Key topics covered:
- Schema design principles (nullable by default)
- Connection pattern for lists (edges, nodes, pageInfo)
- Input types for mutations
- Query design patterns
- Field-level error handling

### gRPC API Design
**See: `references/grpc-api.md`**

Key topics covered:
- Proto file structure
- Service and message definitions
- gRPC status codes mapping to HTTP equivalents

### Frontend API Integration
**See: `references/frontend-integration.md`**

Key topics covered:
- Runtime validation with Zod
- Request interceptors with ky
- Error enrichment pattern
- TanStack Query integration

---

## Quick Reference: HTTP Status Codes

| Code | Name | Use Case |
|------|------|----------|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Invalid request |
| 401 | Unauthorized | Missing auth |
| 403 | Forbidden | No permission |
| 404 | Not Found | Resource missing |
| 409 | Conflict | Duplicate |
| 422 | Unprocessable | Validation failed |
| 429 | Too Many Requests | Rate limited |
| 500 | Internal Error | Server error |

## Quick Reference: Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "Email is already registered" }
    ],
    "request_id": "req_abc123"
  }
}
```

---

## Common Pitfalls

| Pitfall | Bad | Good |
|---------|-----|------|
| Verbs in URLs | `POST /createUser` | `POST /users` |
| Inconsistent naming | `/users, /userOrders` | `/users, /orders` |
| Ignoring HTTP methods | `POST /users/123/delete` | `DELETE /users/123` |
| Exposing internals | `/users-table` | `/users` |
| Generic errors | `"Something went wrong"` | `"Email already exists"` |

---

## Best Practices Summary

1. **Use plural nouns** for resources: `/users`, `/orders`
2. **Use kebab-case** for multi-word: `/user-preferences`
3. **Use hierarchical URLs**: `/users/123/orders`
4. **Cursor pagination** for large datasets
5. **URI versioning** for public APIs: `/api/v1/users`
6. **Include rate limit headers** in responses
7. **Validate with Zod** on frontend boundary
8. **Include request_id** in error responses

---

## Integration with Agents

| Agent | Usage |
|-------|-------|
| **backend-system-architect** | Designs new APIs using this framework |
| **frontend-ui-developer** | Reviews contracts, integrates with APIs |
| **code-quality-reviewer** | Validates API designs against standards |

---

## Related Skills

- `fastapi-advanced` - FastAPI-specific implementation patterns for the API designs in this skill
- `error-handling-rfc9457` - RFC 9457 Problem Details standard for structured error responses
- `api-versioning` - Detailed versioning strategies beyond the basics covered here
- `rate-limiting` - Advanced rate limiting implementations and algorithms

## Key Decisions

| Decision | Choice | Rationale |
|----------|--------|-----------|
| Pagination default | Cursor-based | More efficient for large datasets, stable under inserts/deletes |
| Error format | Structured JSON with request_id | Enables debugging, correlation, and consistent client handling |
| Versioning strategy | URI path (`/api/v1/`) | Most explicit, works with all clients, easy to document |
| Resource naming | Plural nouns, kebab-case | Industry standard, consistent, avoids verb confusion |

---

**Skill Version**: 1.2.0
**Last Updated**: 2026-01-14

## Changelog

### v1.2.0 (2026-01-14)
- Split into reference files for progressive loading
- Added `references/rest-api.md`
- Added `references/graphql-api.md`
- Added `references/grpc-api.md`
- Added `references/frontend-integration.md`
- Fixed malformed YAML frontmatter

### v1.1.0 (2025-12-29)
- Added Frontend API Integration section
- Added Zod runtime validation patterns
- Added request interceptors with ky
- Added TanStack Query integration examples

## Capability Details

### rest-design
**Keywords:** rest, restful, http, endpoint, route, path, resource, CRUD
**Solves:**
- How do I design RESTful APIs?
- REST endpoint patterns and conventions
- HTTP methods and status codes
- API versioning and pagination

### graphql-design
**Keywords:** graphql, schema, query, mutation, connection, relay
**Solves:**
- How do I design GraphQL APIs?
- Schema design best practices
- Connection pattern for pagination

### grpc-design
**Keywords:** grpc, protobuf, proto, rpc, streaming
**Solves:**
- How do I design gRPC services?
- Proto file structure
- gRPC status codes

### endpoint-design
**Keywords:** endpoint, route, path, resource, CRUD
**Solves:**
- How do I structure API endpoints?
- What's the best URL pattern for this resource?
- RESTful endpoint naming conventions

### pagination
**Keywords:** pagination, paginate, paging, offset, cursor, limit
**Solves:**
- How do I add pagination to an endpoint?
- Cursor vs offset pagination
- Pagination best practices

### versioning
**Keywords:** version, v1, v2, api version, breaking change
**Solves:**
- How do I version my API?
- When to create a new API version
- URL vs header versioning

### error-handling
**Keywords:** error, exception, status code, error response, validation error
**Solves:**
- How do I structure error responses?
- Which HTTP status codes to use
- Error message best practices

### rate-limiting
**Keywords:** rate limit, throttle, quota, requests per second, 429
**Solves:**
- How do I implement rate limiting?
- Rate limit headers and responses
- Tiered rate limiting strategies

### authentication
**Keywords:** auth, authentication, bearer, jwt, oauth, api key
**Solves:**
- How do I secure API endpoints?
- JWT vs API key authentication
- OAuth2 flow for APIs

### frontend-integration
**Keywords:** zod, validation, fetch, ky, tanstack, react-query
**Solves:**
- How do I consume APIs with type safety?
- Runtime validation of API responses
- Request interceptors and error handling

Overview

This skill is a comprehensive API design framework covering REST, GraphQL, and gRPC patterns for building consistent, secure, and maintainable services. It provides concrete conventions for endpoints, pagination, versioning, error formats, and frontend integration to speed design and reduce common mistakes.

How this skill works

The framework inspects protocol-specific concerns and recommends standardized patterns: resource naming and HTTP semantics for REST, schema and connection patterns for GraphQL, and proto/service structure for gRPC. It also prescribes supporting practices such as pagination strategy, rate limiting headers, structured error payloads with request_id, and frontend validation/integration techniques.

When to use it

Designing new APIs or adding endpoints for microservices
Choosing between REST, GraphQL, or gRPC for a service
Establishing team-wide API conventions and review checklists
Implementing pagination, rate limiting, authentication, or error schemas
Migrating or versioning existing public or internal APIs

Best practices

Prioritize developer experience: clear names, predictable responses, and helpful errors
Prefer consistency over cleverness: follow established HTTP and schema conventions
Design for evolution: use URI versioning and define deprecation/migration paths
Use cursor-based pagination for large datasets and include rate limit headers
Return structured error objects with request_id for observability and debugging
Validate boundaries (e.g., Zod on frontend) and use typed contracts for integration

Example use cases

Designing a RESTful users/orders API with plural resources, hierarchical routes, and proper HTTP verbs
Modeling GraphQL schemas using connections (edges/nodes/pageInfo) for efficient pagination
Defining proto files and streaming semantics for high-throughput gRPC services
Adding cursor pagination and filtering to an existing listing endpoint to improve performance
Implementing a consistent error response format and attaching request_id for tracing

FAQ

When should I pick GraphQL over REST?

Choose GraphQL when clients need flexible queries and shaped responses, or when minimizing round trips matters; prefer REST for simple resource-centric CRUD and broad client compatibility.

Why use cursor pagination instead of offset?

Cursor pagination scales better and remains stable under inserts/deletes, making it the safer default for large or frequently-changing datasets.