archety/teams-players-api-in-memory repository overview

⁠Team Manager API

A simple Spring Boot REST API designed for Docker and Kubernetes labs.

This project provides a complete in-memory Team Management API with sample data loaded at startup.
The main goal is to let students:

• pull a Docker image
• run the container locally
• push and pull images from a registry
• deploy the application to Kubernetes
• test REST endpoints
• work with probes and service exposure
• practice a simple One To Many data model

⁠Project goals

This project is intentionally simple and focuses on:

• Spring Boot REST APIs
• One To Many modeling
• containerization with Docker
• image distribution through a registry
• deployment on Kubernetes
• testing endpoints with sample in-memory data

There is no external database.
All team and player data is stored in memory, so every restart resets the dataset.

⁠Tech stack

• Java 17
• Spring Boot 3
• Spring Web
• Spring Boot Actuator
• Spring Validation
• Maven
• Docker
• Kubernetes

⁠Project structure

team-manager-api/
|-- pom.xml
|-- Dockerfile
|-- .dockerignore
|-- k8s/
|   |-- deployment.yaml
|   `-- service.yaml
`-- src/
    `-- main/
        |-- java/
        |   `-- dev/archety/teammanager/
        |       |-- Img03TmsApplication.java
        |       |-- config/
        |       |   `-- DataSeeder.java
        |       |-- controller/
        |       |   |-- TeamController.java
        |       |   `-- HomeController.java
        |       |-- dto/
        |       |-- exception/
        |       |-- model/
        |       |-- repository/
        |       `-- service/
        `-- resources/
            `-- application.properties

⁠Features

• Full CRUD for teams
• One To Many relationship between teams and players
• Add, update, and remove players inside a team
• Search teams by league and status
• Sample data loaded automatically at startup
• In-memory repository
• Health endpoint for Kubernetes probes
• Version endpoint for rollout verification
• Ready-to-use Dockerfile
• Ready-to-use Kubernetes manifests

⁠YouTube channel

Educational content, labs, and developer-focused videos by Giovanni Pace:

https://www.youtube.com/@archetydev⁠

⁠Base URL

When running locally:

http://localhost:8082

Base API path:

/api/teams

⁠One To Many model

This project demonstrates a simple One To Many relationship:

• one Team
• many Player

Each team contains a list of players, and player operations are exposed through nested endpoints.

⁠API Endpoints

⁠1. Get all teams

Endpoint

GET /api/teams

Description
Returns the full list of teams currently stored in memory, including their players.

Example request

curl http://localhost:8082/api/teams

Example response

[
  {
    "id": 1,
    "name": "Falcons",
    "city": "Rome",
    "league": "Serie A",
    "status": "ACTIVE",
    "createdAt": "2026-04-13T14:00:00",
    "players": [
      {
        "id": 1,
        "firstName": "Marco",
        "lastName": "Rossi",
        "position": "Goalkeeper",
        "jerseyNumber": 1,
        "status": "AVAILABLE"
      }
    ]
  }
]

⁠2. Get team by ID

Endpoint

GET /api/teams/{id}

Description
Returns a single team by ID with all its players.

Example request

curl http://localhost:8082/api/teams/1

Example response

{
  "id": 1,
  "name": "Falcons",
  "city": "Rome",
  "league": "Serie A",
  "status": "ACTIVE",
  "createdAt": "2026-04-13T14:00:00",
  "players": [
    {
      "id": 1,
      "firstName": "Marco",
      "lastName": "Rossi",
      "position": "Goalkeeper",
      "jerseyNumber": 1,
      "status": "AVAILABLE"
    },
    {
      "id": 2,
      "firstName": "Luca",
      "lastName": "Bianchi",
      "position": "Defender",
      "jerseyNumber": 5,
      "status": "AVAILABLE"
    }
  ]
}

Example not found response

{
  "timestamp": "2026-04-13T14:15:00",
  "status": 404,
  "error": "Not Found",
  "message": "Team with id 99 not found"
}

⁠3. Create a new team

Endpoint

POST /api/teams

Description
Creates a new team in memory.

Example request body

{
  "name": "Wolves",
  "city": "Naples",
  "league": "Serie B",
  "status": "ACTIVE"
}

Example request

curl -X POST http://localhost:8082/api/teams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wolves",
    "city": "Naples",
    "league": "Serie B",
    "status": "ACTIVE"
  }'

Example response

{
  "id": 4,
  "name": "Wolves",
  "city": "Naples",
  "league": "Serie B",
  "status": "ACTIVE",
  "createdAt": "2026-04-13T14:20:00",
  "players": []
}

⁠4. Update a team

Endpoint

PUT /api/teams/{id}

Description
Replaces the full team resource.

Example request body

{
  "name": "Wolves",
  "city": "Naples",
  "league": "Premier League",
  "status": "REBUILDING"
}

Example request

curl -X PUT http://localhost:8082/api/teams/4 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wolves",
    "city": "Naples",
    "league": "Premier League",
    "status": "REBUILDING"
  }'

⁠5. Update only team status

Endpoint

PATCH /api/teams/{id}/status

Description
Updates only the status field of a team.

Example request body

{
  "status": "CHAMPION"
}

Example request

curl -X PATCH http://localhost:8082/api/teams/4/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "CHAMPION"
  }'

⁠6. Add a player to a team

Endpoint

POST /api/teams/{teamId}/players

Description
Adds a child resource to the selected team. This is the main endpoint that demonstrates the One To Many relationship.

Example request body

{
  "firstName": "Paolo",
  "lastName": "Neri",
  "position": "Midfielder",
  "jerseyNumber": 6,
  "status": "AVAILABLE"
}

Example request

curl -X POST http://localhost:8082/api/teams/4/players \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Paolo",
    "lastName": "Neri",
    "position": "Midfielder",
    "jerseyNumber": 6,
    "status": "AVAILABLE"
  }'

Example response

{
  "id": 4,
  "name": "Wolves",
  "city": "Naples",
  "league": "Premier League",
  "status": "REBUILDING",
  "createdAt": "2026-04-13T14:20:00",
  "players": [
    {
      "id": 9,
      "firstName": "Paolo",
      "lastName": "Neri",
      "position": "Midfielder",
      "jerseyNumber": 6,
      "status": "AVAILABLE"
    }
  ]
}

⁠7. Update player status inside a team

Endpoint

PATCH /api/teams/{teamId}/players/{playerId}/status

Description
Updates the status of one player belonging to a specific team.

Example request body

{
  "status": "INJURED"
}

Example request

curl -X PATCH http://localhost:8082/api/teams/4/players/9/status \
  -H "Content-Type: application/json" \
  -d '{
    "status": "INJURED"
  }'

⁠8. Remove a player from a team

Endpoint

DELETE /api/teams/{teamId}/players/{playerId}

Description
Removes a player from the selected team.

Example request

curl -X DELETE http://localhost:8082/api/teams/4/players/9

⁠9. Delete a team

Endpoint

DELETE /api/teams/{id}

Description
Deletes a team by ID.

Example request

curl -X DELETE http://localhost:8082/api/teams/4

Example response

{
  "message": "Team with id 4 deleted successfully"
}

⁠10. Search teams

Endpoint

GET /api/teams/search

Description
Searches teams by optional query parameters:

• league
• status

You can use one of them or both together.

⁠10.1 Search by league

Example request

curl "http://localhost:8082/api/teams/search?league=Serie%20A"

⁠10.2 Search by status

Example request

curl "http://localhost:8082/api/teams/search?status=ACTIVE"

⁠10.3 Search by league and status

Example request

curl "http://localhost:8082/api/teams/search?league=Premier%20League&status=CHAMPION"

⁠11. Count teams

Endpoint

GET /api/teams/count

Description
Returns the total number of teams currently in memory.

Example request

curl http://localhost:8082/api/teams/count

Example response

{
  "count": 3
}

⁠12. Seed info

Endpoint

GET /api/teams/seed-info

Description
Returns information about the preloaded sample dataset.

Example request

curl http://localhost:8082/api/teams/seed-info

Example response

{
  "message": "Sample team data loaded in memory",
  "count": 3
}

⁠13. Ping endpoint

Endpoint

GET /api/teams/ping

Description
Simple test endpoint to verify that the API is running.

Example request

curl http://localhost:8082/api/teams/ping

Example response

{
  "message": "Team Manager API is running"
}

⁠14. Version endpoint

Endpoint

GET /api/teams/version

Description
Returns application metadata useful for Kubernetes rollout checks.

Example request

curl http://localhost:8082/api/teams/version

Example response

{
  "app": "team-manager-api",
  "version": "1.0.0",
  "profile": "k8s-lab"
}

⁠Actuator Endpoints

⁠15. Health endpoint

Endpoint

GET /actuator/health

Description
Used by Kubernetes for readiness and liveness probes.

Example request

curl http://localhost:8082/actuator/health

Example response

{
  "status": "UP"
}

⁠16. Info endpoint

Endpoint

GET /actuator/info

Description
Returns application metadata.

Example request

curl http://localhost:8082/actuator/info

Example response

{
  "app": {
    "name": "team-manager-api",
    "version": "1.0.0",
    "profile": "k8s-lab"
  }
}

⁠Validation rules

The API validates incoming request bodies.

⁠Team creation and update rules

• name: required
• city: required
• league: required
• status: required

⁠Player creation rules

• firstName: required
• lastName: required
• position: required
• jerseyNumber: required, min 0, max 99
• status: required

Example validation error

{
  "timestamp": "2026-04-13T14:30:00",
  "status": 400,
  "error": "Bad Request",
  "validationErrors": {
    "name": "Name is required",
    "jerseyNumber": "Jersey number must be less than or equal to 99"
  }
}

⁠Sample statuses

Allowed values for team status:

• ACTIVE
• REBUILDING
• CHAMPION

Allowed values for player status:

• AVAILABLE
• INJURED
• SUSPENDED

⁠Sample data loaded at startup

The application automatically loads sample teams and players when it starts.

Example teams include:

• Falcons - Rome - Serie A - ACTIVE
• Sharks - Milan - Serie A - REBUILDING
• Titans - Turin - Premier League - CHAMPION

Example players include:

• Marco Rossi - Goalkeeper - AVAILABLE
• Luca Bianchi - Defender - AVAILABLE
• Andrea Verdi - Forward - INJURED
• David Conti - Midfielder - AVAILABLE
• Simone Galli - Forward - SUSPENDED
• Matteo Ferrari - Defender - AVAILABLE
• Alessio Greco - Midfielder - AVAILABLE
• Nicolas Costa - Forward - AVAILABLE

Since everything is stored in memory, restarting the application restores the original dataset.

⁠Running locally

⁠Start the application

mvn spring-boot:run

or build and run the jar:

mvn clean package
java -jar target/team-manager-api.jar

⁠Docker

⁠Build image

docker build -t YOUR_DOCKERHUB_USERNAME/team-manager-api:1.0.0 .

⁠Run container locally

docker run -p 8082:8082 YOUR_DOCKERHUB_USERNAME/team-manager-api:1.0.0

⁠Test container

curl http://localhost:8082/api/teams
curl http://localhost:8082/actuator/health

⁠Push image

docker push YOUR_DOCKERHUB_USERNAME/team-manager-api:1.0.0

Optional latest tag:

docker tag YOUR_DOCKERHUB_USERNAME/team-manager-api:1.0.0 YOUR_DOCKERHUB_USERNAME/team-manager-api:latest
docker push YOUR_DOCKERHUB_USERNAME/team-manager-api:latest

⁠Kubernetes

⁠Apply manifests

kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yaml

⁠Check resources

kubectl get pods
kubectl get deployments
kubectl get svc

⁠Describe deployment

kubectl describe deployment team-manager-api

⁠View logs

kubectl logs -l app=team-manager-api

⁠Kubernetes probes

The deployment uses:

• readinessProbe on /actuator/health
• livenessProbe on /actuator/health

This makes the application suitable for basic Kubernetes health checking demonstrations.

⁠Useful lab activities

Students can use this project to practice:

• pulling a Docker image
• running a container
• testing REST endpoints
• working with nested REST resources
• understanding a simple One To Many model
• pushing a new image version
• updating deployment tags
• scaling replicas
• exposing the service
• observing liveness/readiness probes
• checking rollout results through /api/teams/version

⁠Notes

• No database is used
• Data is reset on every restart
• The project is intentionally simple for infrastructure-focused labs
• It is ideal for Docker and Kubernetes exercises
• The data model is designed to show parent-child REST resource handling

⁠Authoring idea for classroom usage

A good exercise flow could be:

1. pull the image
2. run it with Docker
3. test the team endpoints
4. add players to a team
5. push a new version with a different tag
6. update the Kubernetes deployment
7. verify the new version from /api/teams/version

⁠Coffeeware License

⁠Coffeeware

You can use, modify, share, and distribute this project freely.
If this project helps you, and we ever meet in person, you can buy me a coffee.

Author: Giovanni Pace
YouTube: https://www.youtube.com/@archetydev⁠

⁠Disclaimer

This project is intended for educational purposes.