HTTP

Framework API

Aplikace má framework API vrstvu s health endpointem, OpenAPI specifikací a jednoduchou HTML dokumentací.

Overview

Application has a framework API layer with health endpoint, OpenAPI specification and simple HTML documentation.

Endpoints

Default framework API endpoints:

GET /api/framework/health
GET /api/framework/openapi.json
GET /api/framework/docs

Health endpoint

Health endpoint is used for basic framework API availability checks. It is public and does not require bearer token.

OpenAPI endpoint

OpenAPI endpoint returns OpenAPI 3.1 specification generated from ApiEndpointRegistry. It contains framework endpoints and application endpoints registered via ApiEndpointProviderInterface. In framework default config it is protected. In app config it can be switched to public for development.

Docs endpoint

Docs endpoint returns simple HTML documentation. In framework default config it is disabled and protected. In app config it can be explicitly enabled. For local development it can be public.

Development config example

Example app API config for development mode:

<?php

declare(strict_types=1);

return [
    'enabled' => true,
    'prefix' => '/api',

    'endpoint_providers' => [
        // App\Api\AppApiEndpointProvider::class,
    ],

    'framework' => [
        'openapi' => [
            'access' => 'public',
        ],
        'docs' => [
            'enabled' => true,
            'access' => 'public',
        ],
    ],
];

App endpoint providers

Application endpoints are not added by editing framework routes. They are added through ApiEndpointProviderInterface and configured in app/Config/Api.php under endpoint_providers. OpenAPI output includes them automatically because specification is generated from ApiEndpointRegistry.

'endpoint_providers' => [
    App\Api\AppApiEndpointProvider::class,
];

OpenAPI prefix strategy

OpenAPI uses one consistent strategy: servers.url includes base URL and API prefix, while paths do not include API prefix.

{
  "servers": [
    {
      "url": "https://framework.test/api"
    }
  ],
  "paths": {
    "/framework/health": {},
    "/framework/openapi.json": {},
    "/framework/docs": {}
  }
}

Security note

Framework defaults are secure: health is public, openapi is protected, docs are disabled and protected. App override can switch openapi/docs to public for development. For production, keep openapi/docs protected and enable bearer token.