Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 20 additions & 1 deletion appinfo/routes.php
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
* SPDX-License-Identifier: EUPL-1.2
*/

return [
$routes = [
'routes' => [
// v2 runtime manifest (ADR-036 Decision 8). Registered FIRST so the
// literal '/api/manifest' segment is matched before any wildcard.
Expand All @@ -20,6 +20,8 @@
// Metrics and health
['name' => 'metrics#index', 'url' => '/api/metrics', 'verb' => 'GET'],
['name' => 'health#index', 'url' => '/api/health', 'verb' => 'GET'],
// The OpenAPI document, public (NL API Design Rules, /core/publish-openapi).
['name' => 'openApi#show', 'url' => '/api/openapi.json', 'verb' => 'GET'],

// Store plane (ADR-080). LaunchPad declares a `type: "store"` page, which
// renders CnStorePage, which calls the item routes on mount and on an install
Expand Down Expand Up @@ -654,3 +656,20 @@
'requirements' => ['deepLink' => '(?!api(?:/|$)).+']],
],
];

// The versioned API base (NL API Design Rules, /core/uri-version): every /api/ route
// also answers under /api/v1/, the server URL the OpenAPI document names. The unversioned
// route stays, so existing clients and the URLs the app generates keep working. Each
// copy gets its own route name through 'postfix'. The deep-link catch-all excludes
// /api/, so the copies can follow it.
foreach ($routes['routes'] as $route) {
if (str_starts_with($route['url'], '/api/') === false) {
continue;
}

$route['url'] = '/api/v1/'.substr($route['url'], strlen('/api/'));
$route['postfix'] = ($route['postfix'] ?? '').'V1';
$routes['routes'][] = $route;
}

return $routes;
4 changes: 4 additions & 0 deletions lib/AppInfo/Application.php
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,7 @@
use OCA\LaunchPad\Listener\VersionsListener;
use OCA\LaunchPad\Listener\ViewAnalyticsListener;
use OCA\LaunchPad\Listener\WidgetPlacementsListener;
use OCA\LaunchPad\Middleware\ApiVersionMiddleware;
use OCA\LaunchPad\Notification\Notifier;
use OCA\LaunchPad\Search\LaunchPadSearchProvider;
use OCA\LaunchPad\Service\Connection\ConnectionReporter;
Expand Down Expand Up @@ -104,6 +105,9 @@ public function register(IRegistrationContext $context): void {
// resolved through self::optional(), so an instance without OpenRegister
// gets a store that reports `not_configured` rather than a fatal.
$this->registerStore(context: $context);

// Every /api/ response names the answering API version (NL API Design Rules, /core/version-header).
$context->registerMiddleware(ApiVersionMiddleware::class);
}//end register()

/**
Expand Down
117 changes: 117 additions & 0 deletions lib/Controller/OpenApiController.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,117 @@
<?php

/**
* OpenApiController
*
* Publishes the app's OpenAPI document at `/api/openapi.json`, as the NL API
* Design Rules require (/core/publish-openapi).
*
* @category Controller
* @package OCA\LaunchPad\Controller
* @author Conduction b.v. <info@conduction.nl>
* @copyright 2026 Conduction b.v.
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
* @version GIT:auto
* @link https://conduction.nl
*
* SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
* SPDX-License-Identifier: EUPL-1.2
*/

declare(strict_types=1);

namespace OCA\LaunchPad\Controller;

use OCA\LaunchPad\AppInfo\Application;
use OCP\App\IAppManager;
use OCP\AppFramework\Controller;
use OCP\AppFramework\Http;
use OCP\AppFramework\Http\Attribute\AnonRateLimit;
use OCP\AppFramework\Http\Attribute\NoCSRFRequired;
use OCP\AppFramework\Http\Attribute\PublicPage;
use OCP\AppFramework\Http\JSONResponse;
use OCP\IRequest;
use stdClass;

/**
* GET /api/openapi.json.
*
* @category Controller
* @package OCA\LaunchPad\Controller
* @author Conduction b.v. <info@conduction.nl>
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
* @link https://conduction.nl
*
* @psalm-suppress UnusedClass Instantiated by the Nextcloud router.
*/
class OpenApiController extends Controller {

/**
* Constructor.
*
* @param string $appName The app name.
* @param IRequest $request The request.
* @param IAppManager $appManager Resolves the app path and the installed version.
*
* @psalm-suppress PossiblyUnusedMethod Instantiated via Nextcloud dependency injection.
*/
public function __construct(
string $appName,
IRequest $request,
private readonly IAppManager $appManager,
) {
parent::__construct(appName: $appName, request: $request);
}//end __construct()

/**
* The OpenAPI document of this app, readable from any origin.
*
* The document describes the API, not its data, so it is public. Its
* `info.version` is the installed app version, which is also what every
* API response carries in `API-Version`.
*
* @return JSONResponse The document, or 404 when it is not installed.
*
* @PublicPage
* @NoCSRFRequired
*/
#[PublicPage]
#[NoCSRFRequired]
#[AnonRateLimit(limit: 120, period: 60)]
public function show(): JSONResponse {
$document = $this->document();
$response = new JSONResponse(
['error' => 'The OpenAPI document is not installed'],
Http::STATUS_NOT_FOUND
);
if ($document !== null) {
$document->info->version = $this->appManager->getAppVersion(Application::APP_ID);
$response = new JSONResponse($document);
}

$response->addHeader('Access-Control-Allow-Origin', '*');

return $response;
}//end show()

/**
* The installed OpenAPI document, decoded with empty JSON objects kept as objects.
*
* @return stdClass|null The document, or null when it is missing or not a document.
*
* @psalm-suppress MixedAssignment json_decode() is mixed; the result is checked with instanceof before use.
*/
private function document(): ?stdClass {
$path = $this->appManager->getAppPath(Application::APP_ID).'/openapi.json';
if (is_readable($path) === false) {
return null;
}

$document = json_decode((string) file_get_contents($path), false);
if ($document instanceof stdClass && ($document->info ?? null) instanceof stdClass) {
return $document;
}

return null;
}//end document()
}//end class
101 changes: 101 additions & 0 deletions lib/Middleware/ApiVersionMiddleware.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
<?php

/**
* ApiVersionMiddleware
*
* Every response of a LaunchPad `/api/` endpoint names the version of the API
* that answered in the `API-Version` header, as the NL API Design Rules
* require (/core/version-header). The API version is the installed app
* version, the same value as `info.version` in `/api/openapi.json`.
*
* @category Middleware
* @package OCA\LaunchPad\Middleware
* @author Conduction b.v. <info@conduction.nl>
* @copyright 2026 Conduction b.v.
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
* @version GIT:auto
* @link https://conduction.nl
*
* SPDX-FileCopyrightText: 2026 Conduction B.V. <info@conduction.nl>
* SPDX-License-Identifier: EUPL-1.2
*/

declare(strict_types=1);

namespace OCA\LaunchPad\Middleware;

use OCA\LaunchPad\AppInfo\Application;
use OCP\App\IAppManager;
use OCP\AppFramework\Http\Response;
use OCP\AppFramework\Middleware;
use OCP\IRequest;

/**
* Adds `API-Version` to the responses of LaunchPad's `/api/` endpoints.
*
* @category Middleware
* @package OCA\LaunchPad\Middleware
* @author Conduction b.v. <info@conduction.nl>
* @license EUPL-1.2 https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
* @link https://conduction.nl
*/
class ApiVersionMiddleware extends Middleware {

/**
* The response header that names the answering API version.
*/
public const HEADER = 'API-Version';

/**
* Constructor.
*
* @param IRequest $request The current request.
* @param IAppManager $appManager Resolves the installed app version.
*
* @psalm-suppress PossiblyUnusedMethod Instantiated via Nextcloud dependency injection.
*/
public function __construct(
private readonly IRequest $request,
private readonly IAppManager $appManager,
) {
}//end __construct()

/**
* Name the API version on a response of an `/api/` endpoint.
*
* Other responses (the SPA pages, public shares, kiosk pages) are returned unchanged.
*
* @param \OCP\AppFramework\Controller $controller The controller that answered.
* @param string $methodName The controller method.
* @param Response $response The response.
*
* @return Response The same response.
*
* @SuppressWarnings(PHPMD.UnusedFormalParameter) The signature is the framework's.
*/
public function afterController($controller, $methodName, Response $response): Response {
if ($this->isApiRequest() === false) {
return $response;
}

$version = $this->appManager->getAppVersion(Application::APP_ID);
if ($version === '') {
return $response;
}

$response->addHeader(self::HEADER, $version);

return $response;
}//end afterController()

/**
* Whether the request is for one of the app's `/api/` endpoints.
*
* @return bool True for an `/api/` path.
*/
private function isApiRequest(): bool {
$path = $this->request->getPathInfo();

return is_string($path) === true && str_contains($path, '/api/') === true;
}//end isApiRequest()
}//end class
Loading
Loading