# API Contracts and Endpoints

## Overview

This codebase uses Spring MVC controllers to define the application’s external HTTP surface, while the domain model and repositories provide the backing service interfaces. Most endpoints are server-rendered HTML routes, but a small number also expose JSON-compatible responses for programmatic access.

The contract is intentionally split across a few concerns:

- **Navigation and landing pages**: simple routes such as the home page and error demo endpoint.
- **Owner, pet, and visit workflows**: nested form-driven endpoints that create, update, and display relational data.
- **Veterinarian listings**: a view-oriented HTML page and a JSON-style resource endpoint over the same data.
- **Error behavior**: a controller dedicated to demonstrating exception handling and the framework’s error response rendering.

Because these controllers are tested with MVC slice tests and one integration test, the request/response behavior is part of the codebase’s contract rather than an informal convention.

## Implementation Patterns

### Controller-driven endpoint definition

Each HTTP contract is expressed directly in a controller class with Spring annotations such as `@GetMapping`, `@PostMapping`, `@RequestMapping`, and `@ResponseBody`.

- [WelcomeController](../src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java)
- [CrashController](../src/main/java/org/springframework/samples/petclinic/system/CrashController.java)
- [VetController](../src/main/java/org/springframework/samples/petclinic/vet/VetController.java)
- [OwnerController](../src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java)
- [PetController](../src/main/java/org/springframework/samples/petclinic/owner/PetController.java)
- [VisitController](../src/main/java/org/springframework/samples/petclinic/owner/VisitController.java)

This keeps routing close to the behavior it exposes, and makes the controller class the primary documentation of the external interface.

### View-rendered vs response-body endpoints

The codebase primarily serves HTML views, but there is a deliberate distinction between view-returning handlers and response-body handlers:

- View handlers return view names such as `welcome`, `owners/ownerDetails`, or `pets/createOrUpdatePetForm`.
- Response-body handlers return objects directly, such as the veterinarian listing from [VetController](../src/main/java/org/springframework/samples/petclinic/vet/VetController.java), which is serialized from `Vets`.

This means the same controller can support both user-facing pages and machine-readable output where needed.

### Nested resource routing

The owner domain models a nested REST-like structure even though the UI remains form-oriented:

- Owners are addressed at `/owners` and `/owners/{ownerId}`.
- Pets are nested under `/owners/{ownerId}/pets/...`.
- Visits are nested one level deeper under `/owners/{ownerId}/pets/{petId}/visits/...`.

This nested structure appears in [PetController](../src/main/java/org/springframework/samples/petclinic/owner/PetController.java) and [VisitController](../src/main/java/org/springframework/samples/petclinic/owner/VisitController.java), and it keeps the request path aligned with the ownership model in the domain.

### Binding, validation, and integrity checks

The controllers enforce request contract rules with a combination of binding restrictions and validation:

- `WebDataBinder` disallows binding to identifier fields such as `id` and `*.id`.
- `@Valid` triggers bean validation for owner, pet, and visit form submissions.
- Controller code adds additional contract checks, such as duplicate pet names, future birth dates, and owner ID mismatches.

This is especially visible in [OwnerController](../src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java) and [PetController](../src/main/java/org/springframework/samples/petclinic/owner/PetController.java), where the incoming request is validated before any persistence write occurs.

### Tests as executable contracts

The controller tests assert the expected status codes, views, model attributes, and serialized payloads:

- [VetControllerTests](../src/test/java/org/springframework/samples/petclinic/vet/VetControllerTests.java)
- [OwnerControllerTests](../src/test/java/org/springframework/samples/petclinic/owner/OwnerControllerTests.java)
- [PetControllerTests](../src/test/java/org/springframework/samples/petclinic/owner/PetControllerTests.java)
- [VisitControllerTests](../src/test/java/org/springframework/samples/petclinic/owner/VisitControllerTests.java)
- [CrashControllerTests](../src/test/java/org/springframework/samples/petclinic/system/CrashControllerTests.java)
- [CrashControllerIntegrationTests](../src/test/java/org/springframework/samples/petclinic/system/CrashControllerIntegrationTests.java)

These tests document the expected API behavior and help prevent accidental contract drift.

## Key Classes

### [WelcomeController](../src/main/java/org/springframework/samples/petclinic/system/WelcomeController.java)

Defines the application root route at `/` and maps it to the `welcome` view. It is the simplest example of the server-rendered endpoint style used throughout the application.

### [CrashController](../src/main/java/org/springframework/samples/petclinic/system/CrashController.java)

Exposes `/oups` and deliberately throws a runtime exception. This controller exists to exercise the application’s error rendering path and verify that framework-managed error responses are stable.

### [VetController](../src/main/java/org/springframework/samples/petclinic/vet/VetController.java)

Publishes veterinarian data in two forms:

- `/vets.html` for the HTML view `vets/vetList`
- `/vets` for a response-body representation of `Vets`

It also demonstrates pagination for the view route and repository-backed collection retrieval for both representations.

### [OwnerController](../src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java)

Handles the owner lifecycle:

- create form and submission
- search by last name
- owner details view
- edit form and update submission

It also applies binder restrictions and redirect/flash-message behavior, making it the main contract hub for owner CRUD flows.

### [PetController](../src/main/java/org/springframework/samples/petclinic/owner/PetController.java)

Handles pet creation and editing under a specific owner. This controller is the clearest example of nested path contracts, contextual `@ModelAttribute` loading, and custom validation rules for request data.

### [VisitController](../src/main/java/org/springframework/samples/petclinic/owner/VisitController.java)

Manages visit scheduling for a specific pet under a specific owner. It loads both owner and pet into the model before handling the form and persists the new visit through the owning aggregate.

## How It Fits Together

```mermaid
flowchart TD
APIContracts["API Contracts and Endpoints"] --> WelcomeController["WelcomeController"]
APIContracts --> CrashController["CrashController"]
APIContracts --> VetController["VetController"]
APIContracts --> OwnerController["OwnerController"]
APIContracts --> PetController["PetController"]
APIContracts --> VisitController["VisitController"]
OwnerController --> OwnerRepository["OwnerRepository"]
PetController --> OwnerRepository
PetController --> PetTypeRepository["PetTypeRepository"]
VisitController --> OwnerRepository
VetController --> VetRepository["VetRepository"]
CrashController --> ErrorHandling["Spring Boot error rendering"]
```

The controllers form the public-facing HTTP layer. They translate requests into domain operations through repositories, then either render views or return serialized data. The error controller is a special case that verifies the application’s fallback behavior when a request fails.

## Notes for Developers

- Treat controller tests as part of the contract. If you change a route, view name, model attribute, status code, or redirect target, update the corresponding test immediately.
- Keep nested routes consistent with the ownership model. The path structure should continue to reflect owner → pet → visit relationships.
- Preserve binder protections on identifier fields. They prevent clients from overposting IDs into bound domain objects.
- When adding new endpoints, decide early whether the response is HTML or a serialized body. The codebase supports both, but each has different expectations in tests and consumers.
- Use flash attributes for post/redirect/get flows so success and error messages survive redirects.
- Prefer validation in the controller layer for request-shape checks that are specific to a form or route, and domain/repository checks for persistence-backed existence checks.
- For error-related changes, verify both the unit-level exception behavior and the integration-level rendered response, since the application depends on framework error handling.