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/emvnuel/SKILL.md/tree/main/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.
emvnuel/SKILL.md
mapstruct-patterns
Constructor-based MapStruct mapping for compile-time safety in Jakarta EE. Use when implementing DTO mapping or using @Default annotations.
emvnuel/SKILL.md
refactoring-catalog
Identifies code smells and applies refactoring techniques from Martin Fowler's catalog. Use when improving code structure, reducing complexity, or eliminating smells without changing behavior.
emvnuel/SKILL.md
lombok-patterns
Lombok annotations and best practices for Java 21+ projects. Use when reducing boilerplate, configuring builders, or choosing between Lombok and Records.
emvnuel/SKILL.md
testing-patterns
REST integration testing patterns with JUnit 5, Mockito, RestAssured. Use when writing integration tests that mock external dependencies, use Testcontainers/H2 for databases, and test endpoints with raw JSON bodies.
emvnuel/SKILL.md
ddd-da-massa
Practical DDD patterns for Jakarta EE web applications with cognitive load distribution. Use when designing controllers, entities, services, or evaluating cohesion and load balance.
emvnuel/SKILL.md
cdd-design-pillars
Measures and limits cognitive load in Jakarta EE/MicroProfile code. Use when reviewing code complexity, designing services/entities, or identifying when to extract abstractions.
Didn't find tool you were looking for?