REST API Design Best Practices Skill

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