api-contract-review

name	api-contract-review
description	Use when designing, reviewing, or validating REST API contracts, endpoints, request/response schemas, error handling, and HTTP conventions in Spring Boot applications.

API Contract Review Skill

You are an expert in REST API design for Spring Boot applications. You validate API contracts for consistency, correctness, and adherence to RESTful conventions.

REST Conventions

Resource Naming

// CORRECT - plural nouns, hierarchical
@RestController
@RequestMapping("/api/v1/employees")
public class EmployeeController {

    @GetMapping                              // GET    /api/v1/employees
    @GetMapping("/{id}")                     // GET    /api/v1/employees/42
    @PostMapping                             // POST   /api/v1/employees
    @PutMapping("/{id}")                     // PUT    /api/v1/employees/42
    @DeleteMapping("/{id}")                  // DELETE /api/v1/employees/42
    @GetMapping("/{id}/assignments")         // GET    /api/v1/employees/42/assignments
}

// WRONG - verbs, singular, inconsistent
@RequestMapping("/api/getEmployee")          // verb in URL
@RequestMapping("/api/employee/delete/{id}") // verb in URL
@RequestMapping("/api/emp")                  // abbreviated

HTTP Status Codes

@RestController
@RequestMapping("/api/v1/products")
public class ProductController {

    private final ProductService productService;

    public ProductController(ProductService productService) {
        this.productService = productService;
    }

    @GetMapping("/{id}")
    public ResponseEntity<ProductResponse> getById(@PathVariable Long id) {
        return productService.findById(id)
            .map(ResponseEntity::ok)                              // 200
            .orElseThrow(() -> new ResourceNotFoundException("Product", id)); // 404
    }

    @PostMapping
    public ResponseEntity<ProductResponse> create(
            @Valid @RequestBody CreateProductRequest request) {
        var product = productService.create(request);
        var location = ServletUriComponentsBuilder.fromCurrentRequest()
            .path("/{id}")
            .buildAndExpand(product.id())
            .toUri();
        return ResponseEntity.created(location).body(product);    // 201
    }

    @PutMapping("/{id}")
    public ResponseEntity<ProductResponse> update(
            @PathVariable Long id,
            @Valid @RequestBody UpdateProductRequest request) {
        var product = productService.update(id, request);
        return ResponseEntity.ok(product);                        // 200
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)                        // 204
    public void delete(@PathVariable Long id) {
        productService.delete(id);
    }
}

Consistent Error Responses

public record ApiError(
    Instant timestamp,
    int status,
    String error,
    String message,
    String path,
    List<FieldError> fieldErrors
) {
    public record FieldError(String field, String message) {}
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(ResourceNotFoundException.class)
    public ResponseEntity<ApiError> handleNotFound(
            ResourceNotFoundException ex, HttpServletRequest request) {
        var error = new ApiError(
            Instant.now(),
            404,
            "Not Found",
            ex.getMessage(),
            request.getRequestURI(),
            List.of()
        );
        return ResponseEntity.status(404).body(error);
    }

    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiError> handleValidation(
            MethodArgumentNotValidException ex, HttpServletRequest request) {
        var fieldErrors = ex.getBindingResult().getFieldErrors().stream()
            .map(fe -> new ApiError.FieldError(fe.getField(), fe.getDefaultMessage()))
            .toList();
        var error = new ApiError(
            Instant.now(),
            400,
            "Bad Request",
            "Validation failed",
            request.getRequestURI(),
            fieldErrors
        );
        return ResponseEntity.badRequest().body(error);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handleGeneral(
            Exception ex, HttpServletRequest request) {
        var error = new ApiError(
            Instant.now(),
            500,
            "Internal Server Error",
            "An unexpected error occurred",
            request.getRequestURI(),
            List.of()
        );
        return ResponseEntity.status(500).body(error);
    }
}

Pagination

@GetMapping
public ResponseEntity<Page<ProductResponse>> list(
        @RequestParam(defaultValue = "0") int page,
        @RequestParam(defaultValue = "20") int size,
        @RequestParam(defaultValue = "name,asc") String[] sort) {

    var pageable = PageRequest.of(page, size, Sort.by(
        Sort.Order.by(sort[0]).with(Sort.Direction.fromString(sort.length > 1 ? sort[1] : "asc"))
    ));
    var products = productService.findAll(pageable);
    return ResponseEntity.ok(products);
}

Request Validation

public record CreateProductRequest(
    @NotBlank(message = "Name is required")
    @Size(min = 2, max = 100, message = "Name must be between 2 and 100 characters")
    String name,

    @NotNull(message = "Price is required")
    @Positive(message = "Price must be positive")
    BigDecimal price,

    @Size(max = 500, message = "Description must not exceed 500 characters")
    String description,

    @NotNull(message = "Category is required")
    Long categoryId
) {}

Review Checklist

When reviewing an API contract, verify:

1. Resource names are plural nouns (not verbs)
2. HTTP methods match the operation semantics
3. Status codes are correct (201 for creation, 204 for delete, etc.)
4. Error responses follow a consistent schema
5. Request bodies include validation annotations
6. Pagination is supported for list endpoints
7. Responses never expose internal entity structure
8. URLs are versioned (/api/v1/...)
9. Query parameters use camelCase
10. Sensitive data is never included in URLs