rest-api-design

emvnuel's avatarfrom emvnuel

REST API design patterns and MicroProfile OpenAPI documentation. Use when designing endpoints, choosing HTTP methods, status codes, or documenting APIs with OpenAPI annotations.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025
[API Helpers]

When & Why to Use This Skill

This Claude skill provides a comprehensive framework for designing high-quality RESTful APIs and implementing MicroProfile OpenAPI documentation. It streamlines the development process by offering standardized patterns for endpoint naming, HTTP method selection, status code mapping, and advanced features like pagination and versioning, ensuring your APIs are consistent, intuitive, and industry-compliant.

Use Cases

  • Architecting new RESTful resources using standardized naming conventions (e.g., plural nouns) and hierarchical nesting to improve API discoverability.
  • Selecting the appropriate HTTP methods and status codes to ensure idempotent operations and clear communication of success or error states to API consumers.
  • Implementing robust filtering, sorting, and pagination logic for large datasets to optimize performance and user experience.
  • Automating API documentation using MicroProfile OpenAPI annotations to maintain an accurate and interactive technical reference for developers.
  • Managing API lifecycle and evolution through recommended versioning strategies to ensure backward compatibility and smooth transitions.
namerest-api-design
descriptionREST 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

// ❌ 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

@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