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

rest-api-design

REST API Design Best Practices

Endpoint Design Rules

Use Nouns, Not Verbs