spring-petclinic-rest is the half of Petclinic with no interface

A sample split into a frontend and a backend

spring-petclinic-rest is the REST version of the Spring Petclinic sample application, and the README is clear about the split in the first paragraph. This backend version only provides a REST API and there is no UI. The front end lives in a separate project, spring-petclinic-angular, an Angular application which consumes the REST API.

That structure is the reason this repository exists. The classic Petclinic sample is a server rendered Spring MVC application, which is a fine way to show Spring but a poor way to show a modern front end talking to a backend. Splitting the two gives a project where the API is the contract and the Angular client is a separate consumer, and the topic tags tell you which parts of Spring are in play: spring-mvc, spring-data-jpa, hibernate, jdbc, jackson, openapi, springdoc and swagger.

The domain is a veterinary clinic, which is the long standing Petclinic conceit and a good choice for a sample because it has a natural small schema with relationships, a bit of validation, and read and write paths that exercise a real application rather than a to-do list.

The build and packaging are the other thing the badges advertise. There is a Java build status badge for a Maven build workflow, a Docker build status badge, a SonarCloud quality gate badge and a SonarCloud coverage badge. Four badges is unusual for a sample application, and it says the project treats its own build as an example worth copying.

Two ways to run it, one command each

Running it locally is the first thing a reader will do, and there are two documented routes.

With the Maven wrapper:

git clone https://github.com/spring-petclinic/spring-petclinic-rest.git
cd spring-petclinic-rest
./mvnw spring-boot:run

The wrapper is in the repository as mvnw and mvnw.cmd, with the .mvn/ directory beside it, so the build does not depend on a Maven installation on the machine.

With Docker:

docker run -p 9966:9966 springcommunity/spring-petclinic-rest

Either way you then access petclinic at http://localhost:9966/petclinic/, and there is an Actuator health check route as well at http://localhost:9966/petclinic/actuator/health.

Two details are worth pausing on. The port is 9966 and the application is served under the /petclinic/ context path, so every URL in the project, the API, the Swagger UI, the health check and the H2 console, sits behind that prefix. And the health route is exposed, which is a small thing in a sample and a useful one to copy, because a health endpoint is the difference between a container that reports itself as alive and one that a load balancer can actually route to.

The endpoint table, and the shape of the resource model

The API manages a veterinary clinic's owners, pets, veterinarians, visits and specialties, and the README gives the whole surface as a table.

The pattern is uniform. Each resource gets a collection endpoint that retrieves all of them, an endpoint that fetches one by ID, and create, update and delete endpoints, for example:

| **GET** | `/api/owners` | Retrieve all pet owners |
| **GET** | `/api/owners/{ownerId}` | Get a pet owner by ID |
| **POST** | `/api/owners` | Add a new pet owner |

Owners and pets are related through nested routes as well as through their own collection. A pet can be fetched as an owner's pet at /api/owners/{ownerId}/pets/{petId}, updated there, added to an owner with POST /api/owners/{ownerId}/pets, and given a vet visit through POST /api/owners/{ownerId}/pets/{petId}/visits.

Vets, pet types, specialties and visits each get the five standard endpoints, and users have a single POST /api/users to create a new user. That last line is the only user endpoint in the table, which tells you something about the state of the sample's authentication story, and it is worth knowing before you use this as a base for anything with real users in it.

The uniform CRUD surface is a deliberate teaching choice. A sample that showed you three different styles of controller would teach three styles; a sample that shows the same style for every resource lets you read one controller and predict the others.

OpenAPI 3.1 with a Swagger UI to read it

The API is documented as OpenAPI REST API documentation, and there are two ways in.

Swagger UI is available at http://localhost:9966/petclinic/swagger-ui.html, and the API documentation, described as OAS 3.1, is accessible at http://localhost:9966/petclinic/v3/api-docs.

The second URL is the machine readable one, the OpenAPI document itself, and the fact that it is served by the application rather than checked in as a file is the important detail. A generated spec can drift from the code, and the usual way it drifts is quietly, since nobody regenerates the file. A served spec cannot drift in the same way, because it is produced by the same annotations that produce the controllers.

The spec being OAS 3.1 rather than 3.0 is also worth noting for anyone generating a client from it, since the tooling support for 3.1 is younger than for 3.0, and the springdoc tag in the repository topics is what produces the document.

For a reader trying to understand the project, the Swagger UI is a better entry point than the source, because it shows the request and response shapes that the controllers are annotated with, in one page, for every endpoint at once.

Four databases behind a profile switch

By default Petclinic uses an in-memory H2 database, which is automatically populated with sample data at startup. Four databases are supported, and the choice is made by the spring.profiles.active property in application.properties:

| **H2** (Default)  | `spring.profiles.active=h2,spring-data-jpa` |
| **HSQLDB** (Alternative In-Memory) | `spring.profiles.active=hsqldb,spring-data-jpa` |
| **MySQL** (Persistent) | `spring.profiles.active=mysql,spring-data-jpa` |
| **PostgreSQL** (Persistent) | `spring.profiles.active=postgres,spring-data-jpa` |

The shape of the values is the interesting part. Every profile is combined with spring-data-jpa, so the JPA part of the configuration is always the same and only the datasource varies. Two of the four are in-memory options, H2 and HSQLDB, and two are persistent, MySQL and PostgreSQL.

The default requires no setup at all, since the schema and sample data are loaded automatically from src/main/resources/db/h2/, which is what makes the one command run in the previous section worth anything. Choosing a persistent database is a matter of switching the profile, and the repository ships a docker-compose.yml with MySQL and PostgreSQL services so that the persistent path is testable locally as well.

For a sample, the in-memory default is the right call. A reader who wants to see the application work does not want to create a database first, and the fact that the persistent path is one property away means the sample does not teach a wrong lesson about how to structure that switch.

The H2 console, and the compose services behind the persistent profiles

The H2 section is where the sample teaches you how to look at the data, and the instructions are explicit about the credentials.

You run the application with mvn spring-boot:run, then open the H2 Console in your browser. The URL is http://localhost:9966/petclinic/h2-console, the JDBC URL is jdbc:h2:mem:petclinic, the username is sa and the password is to be left blank.

The blank password and the sa username are correct for an in-memory development database and are exactly the things you must not carry into anything real, so they are worth reading as a demonstration rather than as a recommendation.

The compose file in the repository is the counterpart for the persistent profiles. It defines two services, both behind profiles so that they only start when asked:

services:
  mysql:
    image: mysql:8.4
    command: --mysql-native-password=ON
    ports:
      - "3306:3306"
    environment:
      - MYSQL_ROOT_PASSWORD=
      - MYSQL_ALLOW_EMPTY_PASSWORD=true
      - MYSQL_USER=petclinic
      - MYSQL_PASSWORD=petclinic
      - MYSQL_DATABASE=petclinic

and a PostgreSQL service on image postgres:16.3, port 5432, with the same petclinic user and database, under a postgres profile. MySQL 8.4 with the native password option turned on is the detail to note, since MySQL 8.4 changed the default authentication plugin and a client that does not expect it fails to connect with a confusing error.

Again the empty root password is a development convenience, and the compose profiles mean neither database starts unless you ask for it.

A sample to read, not a framework to depend on

The honest way to describe this repository is as a reference implementation with a small, complete domain, and the alternative to it is the framework version of Petclinic.

The classic spring-framework-petclinic extension is a server rendered application with a UI, and it is the better thing to read if you want to see how Spring MVC views and forms fit together. This repository is the better thing to read if you want to see a REST API with an OpenAPI document, a persistence layer behind JPA, Actuator and a container image, with the front end as a separate client. The Angular project is the third piece, and reading the two of them together shows a contract and its consumer, which is the shape most production services have.

For anyone planning to fork it, the limits are worth stating. There is one documented user endpoint and no authentication, the domain is a placeholder, and the error handling and validation are what a sample needs rather than what a service needs. The repository does not advertise production readiness, and the badges it does advertise are about build, quality gate and coverage, which is the right set of claims for a sample.

The maintenance picture is healthy. The releases are v4.0.2 on 2026-02-01, v3.4.0 on 2024-12-28 and v3.2.1 on 2024-08-15, so the 4.x line is the current one and the step from 3.x to 4.x was a major version rather than a drift. The repository is not archived and the last push was on 2026-10-04, so the sample is being kept in step with the Spring release train rather than left to rot, which is the main risk with a sample of this age. There is also a postman-tests.sh at the root for exercising the API from a shell, and a jmeter tag on the repository, which points at how the API is load tested.

Editorial conclusion

spring-petclinic-rest fits a developer who wants a Spring Boot service that shows how persistence, REST controllers, an OpenAPI document, Actuator and container packaging fit together, since it runs in one command and ships a Docker image and a compose file. It does not fit a team looking for a framework, because it is a sample application and the pet clinic domain is a placeholder, and it does not fit anyone who needs authentication, because the only user endpoint documented is a create. Before using it as a starting point, read the endpoint table and the profile list, and treat the SonarCloud quality gate and coverage badges as the baseline your own project should meet rather than as a promise about the code.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. spring-petclinic/spring-petclinic-rest on GitHub