home / skills / emvnuel / skill.md / rest-api-design
This skill helps design robust REST APIs with consistent endpoint naming, proper HTTP methods, status codes, and MicroProfile OpenAPI documentation.
npx playbooks add skill emvnuel/skill.md --skill rest-api-designReview the files below or copy the command above to add this skill to your agents.
---
name: rest-api-design
description: REST API design patterns and MicroProfile OpenAPI documentation. Use when designing endpoints, choosing HTTP methods, status codes, or documenting APIs with OpenAPI annotations.
---
# REST API Design Best Practices
Design consistent, intuitive REST APIs with proper documentation.
---
## Endpoint Design Rules
### Use Nouns, Not Verbs
```java
// ❌ Bad
@GET @Path("/getUsers")
@POST @Path("/createUser")
// ✓ Good
@GET @Path("/users")
@POST @Path("/users")
```
### Use Plural Nouns for Collections
```java
@Path("/users") // Collection
@Path("/users/{id}") // Single resource
@Path("/orders") // Collection
@Path("/orders/{id}") // Single resource
```
### Nest Related Resources (Max 3 Levels)
```java
@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](./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](./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](./cookbook/status-codes.md)
---
## Filtering & Pagination
```java
@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](./cookbook/filtering-pagination.md)
---
## API Versioning
```java
// URL path versioning (recommended)
@Path("/v1/users")
public class UserResourceV1 { }
@Path("/v2/users")
public class UserResourceV2 { }
```
**Cookbook**: [versioning.md](./cookbook/versioning.md)
---
## MicroProfile OpenAPI Documentation
```java
@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/openapi-documentation.md)
---
## Cookbook Index
**Design**: [Endpoint Design](./cookbook/endpoint-design.md) · [HTTP Methods](./cookbook/http-methods.md)
**Responses**: [Status Codes](./cookbook/status-codes.md)
**Querying**: [Filtering & Pagination](./cookbook/filtering-pagination.md)
**Evolving**: [Versioning](./cookbook/versioning.md)
**Documentation**: [OpenAPI Documentation](./cookbook/openapi-documentation.md)
This skill provides practical REST API design patterns and MicroProfile OpenAPI documentation guidance. It helps you design consistent endpoints, choose correct HTTP methods and status codes, and annotate resources for clear API docs. Use it to build intuitive, versionable, and well-documented REST services.
The skill inspects endpoint naming, resource nesting, HTTP method semantics, status code selection, filtering/pagination patterns, and versioning strategies. It also shows how to apply MicroProfile OpenAPI annotations to expose operations, tags, and response metadata. Outputs are prescriptive rules, code snippets, and documentation examples you can apply directly to resource classes.
When should I use URL versioning vs header versioning?
Use path-based versioning (e.g., /v1/) for clarity and cache-friendly URLs; reserve header versioning for internal or advanced compatibility scenarios.
Should I always use plural nouns for resources?
Yes—plural nouns make collection endpoints intuitive (e.g., /users) and simplify conventions for single-resource paths (/users/{id}).