api-contract-review

name	api-contract-review
description	REST API design validation, OpenAPI review, and contract-first development patterns

API Contract Review

REST API Design Standards

Resource Naming

GET    /api/v1/orders              # List orders (with pagination)
GET    /api/v1/orders/{id}         # Get single order
POST   /api/v1/orders              # Create order
PUT    /api/v1/orders/{id}         # Full update
PATCH  /api/v1/orders/{id}         # Partial update
DELETE /api/v1/orders/{id}         # Delete order
GET    /api/v1/orders/{id}/items   # Sub-resource listing
POST   /api/v1/orders/{id}/cancel  # Action on resource

HTTP Status Codes

// 200 OK - successful GET, PUT, PATCH
@GetMapping("/{id}")
public ResponseEntity<OrderDto> getOrder(@PathVariable String id) {
    return ResponseEntity.ok(orderService.findById(id));
}

// 201 Created - successful POST with Location header
@PostMapping
public ResponseEntity<OrderDto> createOrder(
        @Valid @RequestBody CreateOrderRequest request) {
    var order = orderService.create(request);
    var location = ServletUriComponentsBuilder.fromCurrentRequest()
        .path("/{id}").buildAndExpand(order.id()).toUri();
    return ResponseEntity.created(location).body(order);
}

// 204 No Content - successful DELETE
@DeleteMapping("/{id}")
public ResponseEntity<Void> deleteOrder(@PathVariable String id) {
    orderService.delete(id);
    return ResponseEntity.noContent().build();
}

// 400 Bad Request - validation failure
// 401 Unauthorized - missing or invalid authentication
// 403 Forbidden - insufficient permissions
// 404 Not Found - resource does not exist
// 409 Conflict - business rule violation
// 422 Unprocessable Entity - semantic validation failure
// 429 Too Many Requests - rate limit exceeded

Request and Response DTOs

// Request DTO with validation
public record CreateOrderRequest(
    @NotBlank String customerId,
    @NotEmpty @Valid List<OrderItemRequest> items,
    @Size(max = 500) String notes
) {}

public record OrderItemRequest(
    @NotBlank String productId,
    @Min(1) @Max(1000) int quantity
) {}

// Response DTO with consistent structure
public record OrderDto(
    String id,
    String customerId,
    List<OrderItemDto> items,
    OrderStatus status,
    BigDecimal totalAmount,
    String currency,
    Instant createdAt,
    Instant updatedAt
) {}

// Paginated response
public record PagedResponse<T>(
    List<T> content,
    int page,
    int size,
    long totalElements,
    int totalPages,
    boolean hasNext
) {
    public static <T> PagedResponse<T> from(Page<T> page) {
        return new PagedResponse<>(
            page.getContent(), page.getNumber(), page.getSize(),
            page.getTotalElements(), page.getTotalPages(), page.hasNext());
    }
}

Error Response Format

// RFC 7807 Problem Detail
public record ErrorResponse(
    String type,
    String title,
    int status,
    String detail,
    String instance,
    Map<String, Object> extensions
) {}

// Example error response:
// {
//   "type": "https://api.example.com/errors/insufficient-stock",
//   "title": "Insufficient Stock",
//   "status": 422,
//   "detail": "Product 'prod-1' has only 5 units available, but 10 were requested",
//   "instance": "/api/v1/orders",
//   "extensions": { "productId": "prod-1", "available": 5, "requested": 10 }
// }

OpenAPI Documentation

@RestController
@RequestMapping("/api/v1/orders")
@Tag(name = "Orders", description = "Order management operations")
public class OrderController {

    @Operation(
        summary = "Create a new order",
        description = "Creates an order for the specified customer and items",
        responses = {
            @ApiResponse(responseCode = "201", description = "Order created",
                content = @Content(schema = @Schema(implementation = OrderDto.class))),
            @ApiResponse(responseCode = "400", description = "Invalid request body"),
            @ApiResponse(responseCode = "422", description = "Business rule violation")
        })
    @PostMapping
    public ResponseEntity<OrderDto> createOrder(
            @Valid @RequestBody CreateOrderRequest request) {
        // implementation
    }
}

Contract Review Checklist

1. Naming -- Resources are nouns (plural), actions use HTTP methods
2. Versioning -- API version in URL path (/api/v1/...)
3. Status Codes -- Correct HTTP status for each response scenario
4. Validation -- Request DTOs have Bean Validation annotations
5. Pagination -- List endpoints support pagination with consistent format
6. Error Format -- RFC 7807 Problem Detail for all error responses
7. HATEOAS -- Links included where navigation is needed
8. Content Type -- Explicit Accept and Content-Type handling
9. Idempotency -- PUT and DELETE are idempotent, POST uses idempotency keys
10. Security -- Authentication and authorization documented per endpoint
11. Rate Limiting -- Rate limit headers in responses
12. Deprecation -- Deprecated endpoints marked with Sunset header