majiayu000/spellbook / skills/api-design
api-design
VerifiedREST/GraphQL/gRPC API design best practices. Use when designing APIs, defining contracts, handling versioning. Covers OpenAPI 3.2, GraphQL Federation, gRPC streaming.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| reference/comparison.md | markdown | 6.1 KB |
| reference/graphql.md | markdown | 6.2 KB |
| reference/grpc.md | markdown | 7.4 KB |
| reference/rest.md | markdown | 5.3 KB |
| templates/graphql/schema.graphql | other | 4.5 KB |
| templates/grpc/service.proto | other | 6.0 KB |
| templates/openapi/openapi.yaml | config | 8.3 KB |
templates/graphql/schema.graphql
View on GitHub# Example GraphQL Schema following best practices
scalar DateTime
scalar UUID
# ============================================
# Query
# ============================================
type Query {
"""Get a user by ID"""
user(id: ID!): User
"""List users with pagination and filtering"""
users(
first: Int = 20
after: String
filter: UserFilter
): UserConnection!
"""Get an order by ID"""
order(id: ID!): Order
"""List orders for authenticated user"""
orders(
first: Int = 20
after: String
filter: OrderFilter
): OrderConnection!
}
# ============================================
# Mutations
# ============================================
type Mutation {
"""Create a new user"""
createUser(input: CreateUserInput!): CreateUserPayload!
"""Update an existing user"""
updateUser(id: ID!, input: UpdateUserInput!): UpdateUserPayload!
"""Delete a user"""
deleteUser(id: ID!): DeleteUserPayload!
"""Create a new order"""
createOrder(input: CreateOrderInput!): CreateOrderPayload!
"""Update order status"""
updateOrderStatus(id: ID!, status: OrderStatus!): UpdateOrderPayload!
}
# ============================================
# Subscriptions
# ============================================
type Subscription {
"""Subscribe to order status updates"""
orderUpdated(orderId: ID!): Order!
"""Subscribe to new orders for the authenticated user"""
newOrder: Order!
}
# ============================================
# Types
# ============================================
type User {
id: ID!
email: String!
name: String!
status: UserStatus!
orders(first: Int = 10, after: String): OrderConnection!
createdAt: DateTime!
updatedAt: DateTime
}
enum UserStatus {
ACTIVE
INACTIVE
SUSPENDED
}
type Order {
id: ID!
user: User!
items: [OrderItem!]!
status: OrderStatus!
total: Float!
createdAt: DateTime!
updatedAt: DateTime
}
type OrderItem {
id: ID!
productId: ID!
productName: String!
quantity: Int!
unitPrice: Float!
subtotal: Float!
}
enum OrderStatus {
PENDING
PROCESSING
SHIPPED
DELIVERED
CANCELLED
}
# ============================================
# Connections (Relay-style pagination)
# ============================================
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type UserEdge {
node: User!
cursor: String!
}
type OrderConnection {
edges: [OrderEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type OrderEdge {
node: Order!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# ============================================
# Inputs
# ============================================
input UserFilter {
status: UserStatus
search: String
}
input OrderFilter {
status: OrderStatus
dateFrom: DateTime
dateTo: DateTime
}
input CreateUserInput {
email: String!
name: String!
}
input UpdateUserInput {
name: String
status: UserStatus
}
input CreateOrderInput {
items: [OrderItemInput!]!
}
input OrderItemInput {
productId: ID!
quantity: Int!
}
# ============================================
# Payloads (Union-based error handling)
# ============================================
union CreateUserPayload = CreateUserSuccess | ValidationError | ConflictError
union UpdateUserPayload = UpdateUserSuccess | ValidationError | NotFoundError
union DeleteUserPayload = DeleteUserSuccess | NotFoundError
union CreateOrderPayload = CreateOrderSuccess | ValidationError
union UpdateOrderPayload = UpdateOrderSuccess | NotFoundError | InvalidStateError
type CreateUserSuccess {
user: User!
}
type UpdateUserSuccess {
user: User!
}
type DeleteUserSuccess {
deletedId: ID!
}
type CreateOrderSuccess {
order: Order!
}
type UpdateOrderSuccess {
order: Order!
}
# ============================================
# Errors (typed)
# ============================================
interface Error {
message: String!
code: String!
}
type ValidationError implements Error {
message: String!
code: String!
field: String
details: [FieldError!]
}
type FieldError {
field: String!
message: String!
}
type NotFoundError implements Error {
message: String!
code: String!
resourceType: String!
resourceId: ID!
}
type ConflictError implements Error {
message: String!
code: String!
conflictingField: String!
}
type InvalidStateError implements Error {
message: String!
code: String!
currentState: String!
allowedTransitions: [String!]!
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |