Minimal RESTful JSON API — Slim Framework 4 (Build 68)

A lightweight, high-performance RESTful JSON API built with PHP 8.3, Slim Framework 4, SQLite Database (PDO), Docker Containerization, CLI Health Diagnostics Prober, GitHub Actions CI, OpenAPI 3.0 Documentation & Swagger UI, PSR-7 Request/Response interfaces, PSR-15 Middleware pipeline (CORS, Request Tracing, Rate Limiting, Bearer Authentication, Input Validation, Body Parser, Content-Type), and unit tests powered by PHPUnit.

Stack

• Language / Runtime: PHP 8.3
• Framework: Slim 4 (slim/slim)
• Database Engine: SQLite 3 via PHP PDO
• Containerization: Docker & Docker Compose (PHP 8.3 Alpine)
• Documentation Engine: OpenAPI 3.0 & Swagger UI v5
• HTTP Engine: Slim PSR-7 (slim/psr7)
• CI / CD Pipeline: GitHub Actions (PHP 8.2 & 8.3 matrix testing)
• Architecture: PSR-7 Request/Response, PSR-15 Middleware Pipeline, Action Controllers, Domain Service Layer (Repository Pattern), Standalone CLI Health Prober
• Testing: PHPUnit 10 (phpunit/phpunit)

Quick Start / Running Locally

Prerequisites

• PHP 8.1 or higher with pdo_sqlite extension enabled
• Composer
• Docker & Docker Compose (Optional for containerized execution)

Installation

# Clone the repository
git clone https://github.com/breakingthebot/minimal-json-api-build68.git
cd minimal-json-api-build68

# Install dependencies
composer install

Option A: Local PHP Development Server

php -S localhost:8080 -t public

Option B: Docker Compose Container Setup

# Build and start container in background
docker compose up -d --build

# View container logs
docker compose logs -f

# Check container health status
docker ps

Interactive Documentation & Endpoints

• Swagger UI Playground: http://localhost:8080/docs
• OpenAPI 3.0 Schema: http://localhost:8080/openapi.json
• GET http://localhost:8080/api/v1/health
• GET http://localhost:8080/api/v1/status
• GET http://localhost:8080/api/v1/items
• GET http://localhost:8080/api/v1/items?category=Framework
• GET http://localhost:8080/api/v1/items?search=Slim&limit=2&offset=0
• GET http://localhost:8080/api/v1/items/1
• POST http://localhost:8080/api/v1/items (Requires Authorization: Bearer secret-token-123)
• PUT http://localhost:8080/api/v1/items/1 (Requires Authorization: Bearer secret-token-123)
• DELETE http://localhost:8080/api/v1/items/1 (Requires Authorization: Bearer secret-token-123)

CLI System Diagnostics & Health Prober

Run automated system diagnostics directly from your command line for container liveness and deployment pipeline health checks:

# Human-readable report
php bin/health-check.php

# JSON formatted report
php bin/health-check.php --json

# Quiet mode (exit code 0 = healthy, exit code 1 = unhealthy)
php bin/health-check.php --quiet

(Composer alias shortcut: composer health-check)

Run Test Suite & CI Validation

# Run PHPUnit tests locally
vendor/bin/phpunit

# Validate composer configuration
composer validate --strict

Continuous Integration (GitHub Actions)

This repository uses GitHub Actions (.github/workflows/ci.yml) to automatically execute the following checks on every push and pull request against main:

1. Matrix build validation across PHP 8.2 and PHP 8.3
2. Composer configuration validation (composer validate --strict)
3. Dependency caching and installation (composer install)
4. Full PHPUnit test suite execution (vendor/bin/phpunit)
5. CLI health diagnostics prober verification (php bin/health-check.php --json)

Response Headers & CORS Telemetry

All HTTP responses include standard cross-origin, correlation tracing, rate limiting, and execution time headers:

• Access-Control-Allow-Origin: * (Configurable allowed cross-origin domain)
• Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, HEAD
• Access-Control-Allow-Headers: X-Requested-With, Content-Type, Accept, Origin, Authorization, X-Request-ID
• X-Request-ID: Unique correlation UUID/hash assigned to every request lifecycle
• X-Response-Time: Server execution latency in milliseconds (e.g. 1.25ms)
• X-RateLimit-Limit: Maximum requests allowed per window (default: 20)
• X-RateLimit-Remaining: Remaining request quota in current window
• X-RateLimit-Reset: Unix timestamp when request window resets
• Retry-After: Seconds to wait before retrying when HTTP 429 is returned

API Endpoints Overview

Method	Endpoint	Authentication	Description	Status Code
OPTIONS	/*	Public	CORS preflight request handler	204 No Content
GET	/docs	Public	Interactive Swagger UI API playground	200 OK
GET	/openapi.json	Public	Raw OpenAPI 3.0 JSON specification schema	200 OK
GET	/api/v1/health	Public	API health check & timestamp	200 OK / 429
GET	/api/v1/status	Public	System telemetry & PHP runtime info	200 OK / 429
GET	/api/v1/items	Public	List SQL items with query filters (category, search, status, limit, offset)	200 OK / 400 / 429
GET	/api/v1/items/{id}	Public	Get single SQL item by numeric ID	200 OK / 404 / 429
POST	/api/v1/items	Bearer Token	Create item with SQL INSERT & validation rules (name >= 3 chars, status enum)	201 / 401 / 400 / 429
PUT	/api/v1/items/{id}	Bearer Token	Update item resource with SQL UPDATE & validation rules (name >= 3 chars, status enum)	200 / 401 / 400 / 404 / 429
DELETE	/api/v1/items/{id}	Bearer Token	Delete item resource from SQLite database by numeric ID	200 / 401 / 404 / 429

Data Handling & Security

• Docker Containerization: Multi-stage Dockerfile and compose.yaml run non-root system users (appuser) and attach Docker HEALTHCHECK directives invoking bin/health-check.php.
• Resource Management: Complete RESTful CRUD actions (GET, POST, PUT, DELETE) executed via parameterized SQL PDO queries against SQLite database.
• CORS Protection: CorsMiddleware handles browser preflight OPTIONS requests and sets explicit cross-origin headers to secure frontend SPA and cross-domain integrations.
• CI/CD Security: Automated GitHub Actions workflow validates all commits and pull requests against automated regression tests before deployment.
• CLI Diagnostics Prober: bin/health-check.php checks PHP engine compatibility, SQLite database connectivity, and HTTP endpoint readiness.
• Interactive Documentation: Swagger UI at /docs allows visual, interactive testing of all API endpoints directly within the web browser.
• Request Tracing: RequestTracingMiddleware tags every request stream with a unique X-Request-ID correlation token and measures millisecond latency.
• Database Storage: Item resources are stored in SQLite database (var/database.sqlite) via PHP PDO using prepared SQL statements.
• Rate Limiting Protection: RateLimitingMiddleware evaluates client IP request frequencies using a sliding window.
• Bearer Token Security: All state-modifying requests (POST/PUT/DELETE) require a valid Authorization: Bearer <token> header.
• Data Posture: Store minimal data required for API operation. Zero personal data collected or logged.

Architecture Notes

This application uses a modular PSR-7 / PSR-15 architecture with Slim Framework 4. Controllers are decoupled into single-purpose Action classes (HealthAction, GetItemsAction, CreateItemAction, UpdateItemAction, DeleteItemAction, OpenApiJsonAction, SwaggerUiAction), keeping routing logic lean and testable. CORS, distributed request tracing, rate limiting, authentication, request body parsing, parameter validation, and Content-Type response formatting are handled by dedicated PSR-15 middlewares. Automated regression testing is handled by GitHub Actions CI workflows, and containerization is managed by multi-stage Docker builds.

License

MIT License