Agent skill
rest-api-design
REST API design patterns and MicroProfile OpenAPI documentation. Use when designing endpoints, choosing HTTP methods, status codes, or documenting APIs with OpenAPI annotations.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/documents/rest-api-design
SKILL.md
REST API Design Best Practices
Design consistent, intuitive REST APIs with proper documentation.
Endpoint Design Rules
Use Nouns, Not Verbs
// ❌ Bad
@GET @Path("/getUsers")
@POST @Path("/createUser")
// ✓ Good
@GET @Path("/users")
@POST @Path("/users")
Use Plural Nouns for Collections
@Path("/users") // Collection
@Path("/users/{id}") // Single resource
@Path("/orders") // Collection
@Path("/orders/{id}") // Single resource
Nest Related Resources (Max 3 Levels)
@Path("/users/{userId}/orders") // User's orders
@Path("/users/{userId}/orders/{orderId}") // Specific order
@Path("/posts/{postId}/comments") // Post's comments
Cookbook: endpoint-design.md
HTTP Methods
| Method | Purpose | Idempotent | Request Body |
|---|---|---|---|
GET |
Retrieve | Yes | No |
POST |
Create | No | Yes |
PUT |
Replace entirely | Yes | Yes |
PATCH |
Partial update | Yes | Yes |
DELETE |
Remove | Yes | No |
Cookbook: http-methods.md
Status Codes
| Code | Meaning | When to Use |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Successful POST |
| 204 | No Content | Successful DELETE |
| 400 | Bad Request | Validation errors |
| 401 | Unauthorized | Missing/invalid auth |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 422 | Unprocessable Entity | Business rule violation |
| 500 | Internal Error | Unexpected server error |
Cookbook: status-codes.md
Filtering & Pagination
@GET
@Path("/products")
public List<Product> list(
@QueryParam("category") String category,
@QueryParam("minPrice") BigDecimal minPrice,
@QueryParam("sort") @DefaultValue("name") String sort,
@QueryParam("page") @DefaultValue("0") int page,
@QueryParam("size") @DefaultValue("20") int size
) { }
Cookbook: filtering-pagination.md
API Versioning
// URL path versioning (recommended)
@Path("/v1/users")
public class UserResourceV1 { }
@Path("/v2/users")
public class UserResourceV2 { }
Cookbook: versioning.md
MicroProfile OpenAPI Documentation
@Path("/users")
@Tag(name = "Users", description = "User management")
public class UserResource {
@GET
@Path("/{id}")
@Operation(summary = "Get user by ID")
@APIResponse(responseCode = "200", description = "User found")
@APIResponse(responseCode = "404", description = "User not found")
public User getById(@PathParam("id") Long id) { }
}
Cookbook: openapi-documentation.md
Cookbook Index
Design: Endpoint Design · HTTP Methods
Responses: Status Codes
Querying: Filtering & Pagination
Evolving: Versioning
Documentation: OpenAPI Documentation
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?