Download the PHP package pumasoft/puma-api without Composer

PumaAPI

API Gateway for Puma Services

PumaAPI is a lightweight micro API module designed to parse, validate, and authenticate REST requests based on a simple, file-driven contract architecture. It leverages JWT (JSON Web Token) authentication and provides a clean, declarative way to define your API endpoints through JSON contract files.

Table of Contents

• Features
• Requirements
• Installation
• Quick Start
• Architecture Overview
• Manifest Structure
  • Directory Layout
  • Contract File Format
• Validation Rules
• JWT Authentication
• Service Configuration
• Making Outbound API Calls
• Certificate Object
• Error Handling
• Global Configuration Flags
• Complete Usage Example
• Security Considerations
• API Reference

Features

• 📁 File-Based Contract System - Define API contracts using simple JSON files organized by HTTP method
• 🔐 JWT Authentication - Built-in JWT parsing, validation, and signature verification
• ✅ Request Validation - Automatic validation of headers, body, and JWT payloads against contracts
• 🧹 Request Sanitization - Returns only contracted fields, preventing data leakage
• 📤 Outbound API Caller - Built-in HTTP client for making authenticated requests to other services
• 🎯 RESTful Design - Supports GET, POST, PUT, and DELETE methods
• ⚡ Lightweight - Minimal dependencies (only ext-json and ext-curl)
• 🛡️ Secure by Default - Production-ready security with optional development flags

Requirements

• PHP 5.6 or higher
• ext-json extension
• ext-curl extension
• Apache with mod_rewrite (recommended)

Installation

Manual Installation

1. Clone or download the repository
2. Include the autoloader or manually require the necessary files

Quick Start

Architecture Overview

PumaAPI follows a contract-first approach where API behavior is defined through JSON manifest files:

Core Components

Manifest Structure

Directory Layout

The manifest directory follows a RESTful hierarchy:

URL Mapping:

Contract File Format

Each JSON contract defines the expected request format and response structure:

Validation Rules

Validation rules are specified using the <<ruleName>> syntax. Available built-in rules:

Exact Value Matching

If no rule syntax is used, the validator expects an exact match:

This requires the Content-Type header to be exactly application/json.

JWT Authentication

PumaAPI uses JWT Bearer tokens for authentication. Tokens must be sent in the Authorization header:

Token Structure

Generating Tokens

Use the Tokenizer class to generate new tokens:

Service Configuration

Create a service.ini file in your manifest directory:

Configuration Sections

Making Outbound API Calls

Use the Caller class to make authenticated requests to other services:

Certificate Object

After successful validation, the Certificate object provides access to sanitized request data:

Error Handling

PumaAPI uses the Rawr exception class for structured error handling:

HTTP Status Codes

Error Response Format

Production (default):

Development (with PUMA_API_SEND_EXCEPTIONS_IN_RESPONSE):

Global Configuration Flags

⚠️ Warning: These flags are intended for development only. Never enable them in production!

Define these constants in your bootstrap file before instantiating the API class. The presence of the constant enables the feature (the value is ignored).

Complete Usage Example

1. Project Structure

2. Apache Rewrite Rules (.htaccess)

3. Contract File (__manifest/post/auth/login.json)

4. Service Configuration (__manifest/service.ini)

5. Entry Point (index.php)

6. Controller (controllers/AuthController.php)

Security Considerations

1. Keep service.ini secure - This file contains secret keys; ensure it's not web-accessible
2. Use HTTPS - Always use SSL/TLS in production
3. Rotate secrets regularly - Update JWT signing keys periodically
4. Set short expiration times - Use reasonable exp values for tokens
5. Disable development flags - Never use PUMA_API_* constants in production
6. Validate all input - Define comprehensive contracts for all endpoints

API Reference

PumaAPI\Controller\API

PumaAPI\Model\Certificate

PumaAPI\Model\Tokenizer

PumaAPI\Model\Caller

Important

This is a personal side project developed independently in my own time, using my own equipment and resources. It has no connection to any employer, client, or commercial work.