Skip to main content
designing-apis Guides REST and GraphQL API design, endpoint patterns, request/response schemas, versioning, and API best practices. Use when building APIs, designing endpoints, or reviewing API contracts.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/CloudAI-X/opencode-workflow --skill designing-apisThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... name designing-apis description Guides REST and GraphQL API design, endpoint patterns, request/response schemas, versioning, and API best practices. Use when building APIs, designing endpoints, or reviewing API contracts. license MIT compatibility opencode metadata {"category":"design","audience":"developers"}
Designing APIs
Principles and patterns for designing clean, consistent, and maintainable APIs.
When to Use This Skill
Designing new API endpoints
Reviewing API contracts
Planning API versioning strategies
Defining request/response schemas
Building GraphQL schemas
Documenting APIs
REST API Design Principles
Resource-Oriented Design
APIs should be organized around resources , not actions:
GOOD (Resource-oriented):
GET /users โ List users
GET /users/123 โ Get user 123
POST /users โ Create user
PUT /users/123 โ Update user 123
DELETE /users/123 โ Delete user 123
BAD (Action-oriented):
POST /getUsers
POST /createUser
POST /updateUser
POST /deleteUser
HTTP Method Semantics
Method Purpose Idempotent Safe Request Body GET Retrieve resource(s) Yes Yes No POST Create resource No No Yes PUT Replace resource Yes No Yes PATCH Partial update Yes No Yes DELETE Remove resource Yes No Optional
URL Structure Patterns Collection: /users
Item: /users/{id}
Nested: /users/{id}/posts
Action: /users/{id}/activate (POST only, for non-CRUD)
Filter: /users?status=active&role=admin
Pagination: /users?page=2&limit=20
Sort: /users?sort=created_at&order=desc
Request Design
Path Parameters vs Query Parameters Use Path Parameters Query Parameters Resource identification /users/123- Required filters /orgs/456/users- Optional filters - ?status=activePagination - ?page=2&limit=20Sorting - ?sort=name&order=ascSearch - ?q=searchterm
Request Body Patterns
{
"email" : "user@example.com" ,
"name" : "John Doe" ,
"role" : "admin"
}
{
"name" : "Jane Doe"
}
{
"operations" : [
{ "action" : "create" , "data" : { "email" : "..." } } ,
{ "action" : "update" , "id" : "123" , "data" : { "name" : "..." } }
]
}
Response Design
Consistent Response Envelope
{
"data" : { ... } ,
"meta" : {
"timestamp" : "2024-01-15T10:30:00Z" ,
"requestId" : "abc123"
}
}
{
"data" : [ ... ] ,
"meta" : {
"total" : 100 ,
"page" : 2 ,
"limit" : 20 ,
"hasMore" : true }
}
{
"error" : {
"code" : "VALIDATION_ERROR" ,
"message" : "Invalid request data" ,
"details" : [
{ "field" : "email" , "message" : "Invalid email format" }
]
} ,
"meta" : {
"timestamp" : "2024-01-15T10:30:00Z" ,
"requestId" : "abc123"
}
}
HTTP Status Code Guidelines Range Category Common Codes 2xx Success 200 OK, 201 Created, 204 No Content 3xx Redirect 301 Moved, 304 Not Modified 4xx Client Error 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable 5xx Server Error 500 Internal, 502 Bad Gateway, 503 Unavailable
Status Code Decision Tree Success?
โโ Yes
โ โโ Returning data? โ 200 OK
โ โโ Created resource? โ 201 Created
โ โโ No content? โ 204 No Content
โโ No
โโ Client's fault?
โ โโ Bad syntax? โ 400 Bad Request
โ โโ Not authenticated? โ 401 Unauthorized
โ โโ Not authorized? โ 403 Forbidden
โ โโ Not found? โ 404 Not Found
โ โโ Validation failed? โ 422 Unprocessable Entity
โโ Server's fault? โ 500 Internal Server Error
API Versioning Strategies
URL Path Versioning (Recommended) /api/v1/users
/api/v2/users
Pros : Explicit, easy to understand, easy to route
Cons : URL changes between versions
Header Versioning GET /api/users
Accept: application/vnd.myapi.v2+json
Pros : Clean URLs
Cons : Hidden version, harder to test
Query Parameter Versioning Pros : Flexible, easy to test
Cons : Can be forgotten, pollutes query string
GraphQL Design Patterns
Schema-First Design type User {
id : ID!
email : String!
name : String!
posts : [ Post! ] !
createdAt : DateTime!
}
type Post {
id : ID!
title : String!
content : String!
author : User!
createdAt : DateTime!
}
type Query {
user( id : ID! ) : User
users( filter : UserFilter, page : PageInput) : UserConnection!
}
type Mutation {
createUser( input : CreateUserInput! ) : User!
updateUser( id : ID! , input : UpdateUserInput! ) : User!
deleteUser( id : ID! ) : Boolean!
}
Input Types Pattern input CreateUserInput {
email : String!
name : String!
role : Role = USER
}
input UpdateUserInput {
email : String
name : String
role : Role
}
input UserFilter {
status : UserStatus
role : Role
search : String
}
Pagination Patterns
type UserConnection {
edges : [ UserEdge! ] !
pageInfo : PageInfo!
}
type UserEdge {
node : User!
cursor : String!
}
type PageInfo {
hasNextPage : Boolean!
hasPreviousPage : Boolean!
startCursor : String
endCursor : String
}
type UserList {
items : [ User! ] !
total : Int!
page : Int!
limit : Int!
}
Authentication & Authorization
Authentication Patterns Pattern Use Case Header Bearer Token Standard API auth Authorization: Bearer <token>API Key Server-to-server X-API-Key: <key>Basic Auth Simple/legacy systems Authorization: Basic <base64>OAuth 2.0 Third-party integration OAuth flow
Authorization Responses Not authenticated โ 401 Unauthorized
(User identity unknown)
Not authorized โ 403 Forbidden
(User known, but lacks permission)
Error Handling Patterns
Standardized Error Format {
"error" : {
"code" : "RESOURCE_NOT_FOUND" ,
"message" : "User with ID 123 not found" ,
"target" : "user" ,
"details" : [
{
"code" : "INVALID_ID" ,
"message" : "The provided ID does not exist" ,
"target" : "id"
}
] ,
"innererror" : {
"trace" : "abc123" ,
"timestamp" : "2024-01-15T10:30:00Z"
}
}
}
Common Error Codes Code HTTP Status When VALIDATION_ERROR400/422 Request data invalid UNAUTHORIZED401 Auth required FORBIDDEN403 Insufficient permissions NOT_FOUND404 Resource doesn't exist CONFLICT409 State conflict (duplicate) RATE_LIMITED429 Too many requests INTERNAL_ERROR500 Server failure
API Documentation
OpenAPI/Swagger Structure openapi: 3.0 .3
info:
title: My API
version: 1.0 .0
paths:
/users:
get:
summary: List users
parameters:
- name: status
in: query
schema:
type: string
enum: [active , inactive ]
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/UserList'
components:
schemas:
User:
type: object
required: [id , email ]
properties:
id:
type: string
email:
type: string
format: email
Anti-Patterns to Avoid
Verbs in URLs - Use /users not /getUsersIgnoring HTTP Methods - Use proper methods, not POST for everythingInconsistent Naming - Pick snake_case or camelCase, stick with itLeaking Implementation - Don't expose internal IDs or DB structureMissing Pagination - Always paginate collectionsIgnoring Idempotency - PUT/DELETE must be idempotentNo Versioning - Plan for API evolution from day one
Quick Reference RESOURCE DESIGN:
/resources โ Collection
/resources/{id} โ Item
/resources/{id}/sub โ Nested
HTTP METHODS:
GET โ Read (safe, idempotent)
POST โ Create (not idempotent)
PUT โ Replace (idempotent)
PATCH โ Update (idempotent)
DELETE โ Remove (idempotent)
STATUS CODES:
200 OK, 201 Created, 204 No Content
400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found
500 Internal Server Error
VERSIONING:
/api/v1/resources (recommended)
PAGINATION:
?page=2&limit=20 (offset)
?cursor=abc123&limit=20 (cursor)
Related occupations SOC
Based on SOC occupation classification
More from this repository
