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

Cookbook: http-methods.md

Status Codes

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