Parking Service API

Project Status: ✅ Version 1.0 (Complete) ✅

A robust RESTful API for parking service management, built with Django and Django REST Framework. The project is fully containerized with Docker and follows best development practices, including automated tests with high coverage, code linting, and formatting.

🚀 Features

Core Functionality

Customer Management (/api/v1/customers): Complete CRUD operations for customer registration
Vehicle Management (/api/v1/vehicles): CRUD operations for vehicles, associating them with customers
Vehicle Types (/api/v1/vehicles/type): Management of vehicle categories (e.g., Car, Motorcycle)
Parking Control:
- Parking Spots (/api/v1/parking/spots): Management of parking spots
- Parking Records (/api/v1/parking/records): System for registering vehicle entry and exit, with automatic update of spot occupancy status
Authentication: JWT-based authentication system to protect API endpoints
Optimized Admin: Customized administration interface with intelligent vehicle data auto-fill functionality to streamline workflow

API Documentation

Swagger UI: Interactive API documentation at /api/v1/docs/
ReDoc: Alternative API documentation at /api/v1/redoc/
OpenAPI Schema: Available at /api/v1/schema/

🏗️ Architecture Decisions

Vehicle Data Generation

A common requirement in parking systems is the automatic filling of vehicle information (brand, model, color) from the license plate. However, there are no public, free, and legal APIs in Brazil for this purpose. Solutions based on web scraping of government portals were discarded as they are unstable, violate terms of service, and present risks related to LGPD (Brazil's General Data Protection Law).

As a pragmatic and professional solution, a POST endpoint (/api/v1/vehicles/get-by-plate/) was implemented that acts as a simulated data provider:

When a new license plate is provided, the system uses the Faker library to generate fictional data for brand, model, and color
This data is saved in the database
In future queries for the same plate, the previously saved consistent data is returned

This approach demonstrates the ability to work around real-world limitations, ensuring a smooth user experience and allowing the system to function completely and independently, without depending on external services.

Service Layer Architecture

With the goal of following software design best practices, such as the Single Responsibility Principle (SRP), the business logic for vehicle querying and creation was extracted from the API layer (views.py) and isolated in a dedicated service layer (services.py). This refactoring made the code cleaner, more reusable, and much easier to test, demonstrating a commitment to long-term project maintainability.

🛠️ Tech Stack

The project was built with a focus on quality, maintainability, and modern development practices.

Backend & Database

Framework: Django 5.2, Django REST Framework 3.16
Database: PostgreSQL 16
Authentication: djangorestframework-simplejwt for JWT tokens

Development Tools

Containerization: Docker, Docker Compose
Dependency Management: pip and pip-tools (pip-compile)
Testing: pytest, pytest-django, pytest-cov (with 96% test coverage)
Code Quality: Ruff for linting and formatting, pre-commit for automated quality checks
API Documentation: drf-spectacular for automatic OpenAPI 3 schema generation
Admin Interface: django-jazzmin for enhanced admin UI
Query Filtering: django-rql for advanced query filtering

Additional Libraries

Faker: For generating realistic test data
WhiteNoise: For static file serving
Gunicorn: Production WSGI server

📋 Prerequisites

Docker (version 20.10 or higher)
Docker Compose (version 2.0 or higher)

🚀 Getting Started

The project is fully containerized, so all you need is Docker and Docker Compose.

1. Clone the Repository

git clone https://github.com/CFBruna/parking_service.git
cd parking_service

2. Configure Environment Variables

Create a .env.docker file in the root directory with the following variables:

# Database
DATABASE_URL=postgresql://postgres:postgres@db:5432/parking_db

# Django
SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=127.0.0.1,localhost

# Static Files
STATIC_ROOT=/usr/src/app/staticfiles

Note: For development, you can use the default values. Adjust them as needed for production.

3. Build and Start Containers

docker-compose up --build

The --build flag is important the first time to build the Docker image.

4. Run Migrations

In a new terminal, with containers running:

docker-compose exec web python manage.py migrate

5. (Optional) Create a Superuser

To access the Django admin interface:

docker-compose exec web python manage.py createsuperuser

6. Access the Application

API Base URL: http://127.0.0.1:8000/api/v1/
Admin Interface: http://127.0.0.1:8000/admin/
API Documentation (Swagger): http://127.0.0.1:8000/api/v1/docs/
API Documentation (ReDoc): http://127.0.0.1:8000/api/v1/redoc/

🧪 Running Tests

The automated test suite is fundamental to ensure the quality and stability of the project.

Run All Tests

With containers running:

docker-compose exec web pytest

Run Tests with Coverage Report

To see the coverage report in the terminal:

docker-compose exec web pytest --cov

Generate HTML Coverage Report

To generate a detailed HTML coverage report:

docker-compose exec web pytest --cov --cov-report=html

Open the htmlcov/index.html file in your browser to explore the report.

Current Test Coverage: 96% ✅

📚 API Endpoints

Authentication

POST /api/v1/authentication/token/ - Obtain JWT token
POST /api/v1/authentication/token/refresh/ - Refresh JWT token
POST /api/v1/authentication/token/verify/ - Verify JWT token

Customers

GET /api/v1/customers/ - List all customers
POST /api/v1/customers/ - Create a new customer
GET /api/v1/customers/{id}/ - Retrieve a customer
PUT /api/v1/customers/{id}/ - Update a customer
PATCH /api/v1/customers/{id}/ - Partially update a customer
DELETE /api/v1/customers/{id}/ - Delete a customer

Vehicles

GET /api/v1/vehicles/ - List all vehicles
POST /api/v1/vehicles/ - Create a new vehicle
GET /api/v1/vehicles/{id}/ - Retrieve a vehicle
PUT /api/v1/vehicles/{id}/ - Update a vehicle
PATCH /api/v1/vehicles/{id}/ - Partially update a vehicle
DELETE /api/v1/vehicles/{id}/ - Delete a vehicle
POST /api/v1/vehicles/get-by-plate/ - Get or create vehicle data by license plate
GET /api/v1/vehicles/type/ - List all vehicle types
POST /api/v1/vehicles/type/ - Create a new vehicle type
GET /api/v1/vehicles/type/{id}/ - Retrieve a vehicle type
PUT /api/v1/vehicles/type/{id}/ - Update a vehicle type
PATCH /api/v1/vehicles/type/{id}/ - Partially update a vehicle type
DELETE /api/v1/vehicles/type/{id}/ - Delete a vehicle type

Parking

GET /api/v1/parking/spots/ - List all parking spots
POST /api/v1/parking/spots/ - Create a new parking spot
GET /api/v1/parking/spots/{id}/ - Retrieve a parking spot
PUT /api/v1/parking/spots/{id}/ - Update a parking spot
PATCH /api/v1/parking/spots/{id}/ - Partially update a parking spot
DELETE /api/v1/parking/spots/{id}/ - Delete a parking spot
GET /api/v1/parking/records/ - List all parking records
POST /api/v1/parking/records/ - Create a new parking record (entry)
GET /api/v1/parking/records/{id}/ - Retrieve a parking record
PUT /api/v1/parking/records/{id}/ - Update a parking record
PATCH /api/v1/parking/records/{id}/ - Partially update a parking record (exit)
DELETE /api/v1/parking/records/{id}/ - Delete a parking record

Advanced Querying

The API supports RQL (Resource Query Language) for advanced filtering. For example:

GET /api/v1/vehicles/?filter=license_plate=like=ABC*
GET /api/v1/parking/records/?filter=entry_time=ge=2024-01-01T00:00:00Z

See the django-rql documentation for more details.

🔒 Authentication

The API uses JWT (JSON Web Tokens) for authentication. To authenticate:

Obtain a token by making a POST request to /api/v1/authentication/token/ with your credentials:
```
{
  "username": "your_username",
  "password": "your_password"
}
```
Include the token in subsequent requests using the Authorization header:
```
Authorization: Bearer <your_token>
```
Refresh your token using /api/v1/authentication/token/refresh/ when it expires.

🏗️ Project Structure

parking_service/
├── authentication/      # Authentication app
├── customers/           # Customer management app
├── vehicles/            # Vehicle management app
├── parking/             # Parking management app
├── parking_service/     # Main project settings
├── static/              # Static files (images, JS)
├── docker-compose.yml   # Docker Compose configuration
├── Dockerfile           # Docker image definition
├── requirements.txt     # Python dependencies
└── pytest.ini          # Pytest configuration

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

This project is licensed under the terms specified in the LICENSE file.

👤 Author

CFBruna

GitHub: @CFBruna

Made with ❤️ using Django and Django REST Framework

Name		Name	Last commit message	Last commit date
Latest commit History 34 Commits
.github/workflows		.github/workflows
authentication		authentication
customers		customers
parking		parking
parking_service		parking_service
static		static
vehicles		vehicles
.dockerignore		.dockerignore
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
entrypoint.sh		entrypoint.sh
manage.py		manage.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements-dev.txt		requirements-dev.txt
requirements.in		requirements.in
requirements.txt		requirements.txt

License

CFBruna/parking_service

Folders and files

Latest commit

History

Repository files navigation