メニュー
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.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/CloudAI-X/opencode-workflow --skill designing-apisコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
SOC 職業分類に基づく
| 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"} |
Principles and patterns for designing clean, consistent, and maintainable APIs.
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
| 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 |
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
| Use | Path Parameters | Query Parameters |
|---|---|---|
| Resource identification | /users/123 | - |
| Required filters | /orgs/456/users | - |
| Optional filters | - | ?status=active |
| Pagination | - | ?page=2&limit=20 |
| Sorting | - | ?sort=name&order=asc |
| Search | - | ?q=searchterm |
// POST /users - Create
{
"email": "user@example.com",
"name": "John Doe",
"role": "admin"
}
// PATCH /users/123 - Partial update
{
"name": "Jane Doe"
}
// Bulk operations - POST /users/bulk
{
"operations": [
{ "action": "create", "data": { "email": "..." } },
{ "action": "update", "id": "123", "data": { "name": "..." } }
]
}
// Success response
{
"data": { ... },
"meta": {
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "abc123"
}
}
// Collection response with pagination
{
"data": [ ... ],
"meta": {
"total": 100,
"page": 2,
"limit": 20,
"hasMore": true
}
}
// Error response
{
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": [
{ "field": "email", "message": "Invalid email format" }
]
},
"meta": {
"timestamp": "2024-01-15T10:30:00Z",
"requestId": "abc123"
}
}
| 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 |
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/v1/users
/api/v2/users
Pros: Explicit, easy to understand, easy to route Cons: URL changes between versions
GET /api/users
Accept: application/vnd.myapi.v2+json
Pros: Clean URLs Cons: Hidden version, harder to test
/api/users?version=2
Pros: Flexible, easy to test Cons: Can be forgotten, pollutes query string
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 CreateUserInput {
email: String!
name: String!
role: Role = USER
}
input UpdateUserInput {
email: String
name: String
role: Role
}
input UserFilter {
status: UserStatus
role: Role
search: String
}
# Cursor-based (recommended for large datasets)
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
}
type UserEdge {
node: User!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# Offset-based (simpler, for smaller datasets)
type UserList {
items: [User!]!
total: Int!
page: Int!
limit: Int!
}
| 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 |
Not authenticated → 401 Unauthorized
(User identity unknown)
Not authorized → 403 Forbidden
(User known, but lacks permission)
{
"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"
}
}
}
| Code | HTTP Status | When |
|---|---|---|
VALIDATION_ERROR | 400/422 | Request data invalid |
UNAUTHORIZED | 401 | Auth required |
FORBIDDEN | 403 | Insufficient permissions |
NOT_FOUND | 404 | Resource doesn't exist |
CONFLICT | 409 | State conflict (duplicate) |
RATE_LIMITED | 429 | Too many requests |
INTERNAL_ERROR | 500 | Server failure |
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
/users not /getUsersRESOURCE 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)