PHPackages                             baraja-core/structured-api - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. baraja-core/structured-api

ActiveLibrary[API Development](/categories/api)

baraja-core/structured-api
==========================

Complex library for definition of your structured API endpoint as class with schema.

v4.1.1(2y ago)7174.3k[11 issues](https://github.com/baraja-core/structured-api/issues)12PHPPHP ^8.1CI failing

Since Jan 3Pushed 6mo ago1 watchersCompare

[ Source](https://github.com/baraja-core/structured-api)[ Packagist](https://packagist.org/packages/baraja-core/structured-api)[ Docs](https://github.com/baraja-core/structured-api)[ RSS](/packages/baraja-core-structured-api/feed)WikiDiscussions master Synced today

READMEChangelog (10)Dependencies (18)Versions (74)Used By (12)

   ![BRJ logo](https://camo.githubusercontent.com/813c67e02a7ab7e4dc900316a4521c3ddf5846fe2cabba7140f3f4b78afda198/68747470733a2f2f63646e2e62726a2e6170702f696d616765732f62726a2d6c6f676f2f6c6f676f2d6461726b2e706e67)
 [BRJ organisation](https://brj.app)

---

Structured REST API in PHP
==========================

[](#structured-rest-api-in-php)

[![Integrity check](https://github.com/baraja-core/structured-api/workflows/Integrity%20check/badge.svg)](https://github.com/baraja-core/structured-api/workflows/Integrity%20check/badge.svg)

A powerful, type-safe REST API framework for PHP 8.1+ with full Nette Framework integration. Define structured API endpoints as PHP classes with automatic parameter validation, response serialization, and built-in permission management.

🎯 Key Features
--------------

[](#dart-key-features)

- **Type-safe endpoints** - Define full type-hint input parameters with automatic validation
- **Schema-based responses** - Return typed DTOs that are automatically serialized to JSON
- **Automatic endpoint discovery** - Endpoints are auto-registered via Nette DI container
- **Built-in permission system** - Role-based access control with `#[PublicEndpoint]` and `#[Role]` attributes
- **HTTP method routing** - Method names determine HTTP verb (GET, POST, PUT, DELETE)
- **Tracy debugger integration** - Visual debug panel for API request/response inspection
- **CORS handling** - Automatic Cross-Origin Resource Sharing support
- **Dependency injection** - Full DI support via constructor or `#[Inject]` attribute
- **Flash messages** - Built-in flash message system for API responses

🏗️ Architecture Overview
------------------------

[](#building_construction-architecture-overview)

The package follows a layered architecture with clear separation of concerns:

```
┌───────────────────────────────────────────────────────────────┐
│                        HTTP Request                           │
└───────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────────┐
│                         ApiManager                            │
│  ┌───────────────┐  ┌────────────────┐  ┌─────────────────┐  │
│  │  URL Router   │  │  CORS Handler  │  │   Tracy Panel   │  │
│  │ /api/v1/{ep}  │  │  (Preflight)   │  │    (Debug)      │  │
│  └───────┬───────┘  └────────────────┘  └─────────────────┘  │
│          │                                                    │
│          ▼                                                    │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                  Middleware Pipeline                   │  │
│  │  ┌───────────────────┐  ┌──────────────────────────┐  │  │
│  │  │PermissionExtension│  │ Custom MatchExtensions   │  │  │
│  │  │  (Auth & Roles)   │  │ (before/after process)   │  │  │
│  │  └───────────────────┘  └──────────────────────────┘  │  │
│  └────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────────┐
│                          Endpoint                             │
│  ┌───────────────┐  ┌────────────────┐  ┌─────────────────┐  │
│  │ BaseEndpoint  │  │ Method Invoker │  │   Convention    │  │
│  │ (Your Logic)  │  │ (Param Binding)│  │  (Formatting)   │  │
│  └───────┬───────┘  └────────────────┘  └─────────────────┘  │
│          │                                                    │
│          ▼                                                    │
│  ┌────────────────────────────────────────────────────────┐  │
│  │                   Response System                      │  │
│  │  ┌────────────┐  ┌────────────┐  ┌──────────────────┐ │  │
│  │  │DTO Objects │  │ StatusResp │  │   JsonResponse   │ │  │
│  │  │(Your Types)│  │ (Ok/Error) │  │   (Serialized)   │ │  │
│  │  └────────────┘  └────────────┘  └──────────────────┘ │  │
│  └────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌───────────────────────────────────────────────────────────────┐
│                        HTTP Response                          │
│                  (JSON with proper HTTP code)                 │
└───────────────────────────────────────────────────────────────┘

```

### Core Components

[](#core-components)

ComponentDescription**ApiManager**Central orchestrator that handles routing, CORS, middleware execution, and response processing**ApiExtension**Nette DI extension for automatic service registration and configuration**BaseEndpoint**Abstract base class providing helper methods for sending responses**Endpoint**Interface that marks a class as an API endpoint**MetaDataManager**Discovers and registers endpoint classes using RobotLoader**Convention**Configuration entity for response formatting, date formats, and security settings**PermissionExtension**Middleware for authentication and role-based access control**MatchExtension**Interface for creating custom middleware (before/after processing hooks)**Tracy Panel**Debug panel showing request details, parameters, and response data🖼️ Tracy Debug Panel
--------------------

[](#framed_picture-tracy-debug-panel)

The package includes a comprehensive Tracy debug panel for inspecting API requests during development:

[![Baraja Structured API debug Tracy panel](doc/tracy-panel-design.png)](doc/tracy-panel-design.png)

The panel displays:

- HTTP method and request URL
- Raw HTTP input parameters
- Resolved endpoint arguments after type casting
- Response type, HTTP code, and content type
- Complete serialized response data
- Request processing time in milliseconds

📦 Installation
--------------

[](#package-installation)

It's best to use [Composer](https://getcomposer.org) for installation, and you can also find the package on [Packagist](https://packagist.org/packages/baraja-core/structured-api) and [GitHub](https://github.com/baraja-core/structured-api).

To install, simply use the command:

```
$ composer require baraja-core/structured-api
```

### Requirements

[](#requirements)

- PHP 8.1 or higher
- Extensions: `json`, `mbstring`, `iconv`
- Nette Framework 3.x

### Nette Framework Integration

[](#nette-framework-integration)

The package integrates automatically with Nette Framework. A model configuration can be found in the `common.neon` file inside the root of the package.

If you use [PackageRegistrator](https://github.com/baraja-core/package-manager), the extension is registered automatically. Otherwise, register the extension manually in your `config.neon`:

```
extensions:
    structuredApi: Baraja\StructuredApi\ApiExtension
```

### Configuration Options

[](#configuration-options)

```
structuredApi:
    skipError: false  # If true, silently logs API exceptions instead of throwing
```

🚀 Basic Usage
-------------

[](#rocket-basic-usage)

### Creating Your First Endpoint

[](#creating-your-first-endpoint)

Create a class that extends `BaseEndpoint` with the suffix `Endpoint`:

```