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.
الانتقال إلى التثبيت سوق المهارات اكتشف واستكشف مهارات الذكاء الاصطناعي التي بناها المجتمع.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
عرض تفاصيل Prompt يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/CloudAI-X/opencode-workflow --skill designing-apisيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
تحميل Zip جاري التحميل... المزيد من هذا المستودع Guides systematic project analysis, codebase exploration, and architecture pattern recognition. Use when understanding new codebases, onboarding to projects, or investigating system structure.
Guides software architecture decisions, design patterns, and system design principles. Use when designing systems, choosing patterns, or making architectural decisions.
Guides test strategy, TDD/BDD approaches, test coverage planning, and testing best practices. Use when designing test suites, improving coverage, or choosing testing approaches.
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)
المهن ذات الصلة SOC
استنادا إلى تصنيف SOC المهني
