rest-api-design
4
总安装量
2
周安装量
#48990
全站排名
安装命令
npx skills add https://github.com/emvnuel/skill.md --skill rest-api-design
Agent 安装分布
cursor
2
github-copilot
2
claude-code
2
antigravity
2
gemini-cli
2
cline
1
Skill 文档
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