Feature/http api new approach #348

Jan-Schuppik · 2025-08-22T13:51:53Z

Initial setup for the new approach of the http-api with openapi description.

Resolves:

require:

nilmerg

This review covers only the early parts of routing and dispatching.

nilmerg · 2025-08-26T07:50:16Z

run.php

+$this->addRoute('notifications/api-v1-contacts', new Zend_Controller_Router_Route_Regex(
+    'notifications/api/v1/contacts(?:\/(.+)|\?(.+))?',
+    [
+        'controller'    => 'api-v1-contacts',
+        'action'        => 'index',
+        'module'        => 'notifications',
+        'identifier'    => null
+    ],
+    [
+        1 => 'identifier'
+    ]
+));
+
+$this->addRoute('notifications/api-v1-contactgroups', new Zend_Controller_Router_Route_Regex(
+    'notifications/api/v1/contactgroups(?:\/(.+)|\?(.+))?',
+    [
+        'controller'    => 'api-v1-contactgroups',
+        'action'        => 'index',
+        'module'        => 'notifications',
+        'identifier'    => null
+    ],
+    [
+        1 => 'identifier'
+    ]
+));
+
+$this->addRoute('notifications/api-v1-channels', new Zend_Controller_Router_Route_Regex(
+    'notifications/api/v1/channels(?:\/(.+)|\?(.+))?',
+    [
+        'controller'    => 'api-v1-channels',
+        'action'        => 'index',
+        'module'        => 'notifications',
+        'identifier'    => null
+    ],
+    [
+        1 => 'identifier'
+    ]
+));
+
+$this->addRoute('notifications/api-v1-channels', new Zend_Controller_Router_Route_Regex(
+    'notifications/api(?:\/(v[0-9\.]+))(?:\/([^\/\?]+))?(?:[\/\?]([^\/\?]+))?',
+    [
+        'controller'    => 'api',
+        'action'        => 'index',
+        'version'     => 'v1',
+        'module'        => 'notifications',
+        'endpoint'     => null,
+        'identifier'    => null
+    ],
+    [
+        1 => 'version',
+        2 => 'endpoint',
+        3 =>  'identifier'
+    ]
+));


Please replace this with:

Suggested change

$this->addRoute('notifications/api-v1-contacts', new Zend_Controller_Router_Route_Regex(

'notifications/api/v1/contacts(?:\/(.+)|\?(.+))?',

[

'controller' => 'api-v1-contacts',

'action' => 'index',

'module' => 'notifications',

'identifier' => null

],

[

1 => 'identifier'

]

));

$this->addRoute('notifications/api-v1-contactgroups', new Zend_Controller_Router_Route_Regex(

'notifications/api/v1/contactgroups(?:\/(.+)|\?(.+))?',

[

'controller' => 'api-v1-contactgroups',

'action' => 'index',

'module' => 'notifications',

'identifier' => null

],

[

1 => 'identifier'

]

));

$this->addRoute('notifications/api-v1-channels', new Zend_Controller_Router_Route_Regex(

'notifications/api/v1/channels(?:\/(.+)|\?(.+))?',

[

'controller' => 'api-v1-channels',

'action' => 'index',

'module' => 'notifications',

'identifier' => null

],

[

1 => 'identifier'

]

));

$this->addRoute('notifications/api-v1-channels', new Zend_Controller_Router_Route_Regex(

'notifications/api(?:\/(v[0-9\.]+))(?:\/([^\/\?]+))?(?:[\/\?]([^\/\?]+))?',

[

'controller' => 'api',

'action' => 'index',

'version' => 'v1',

'module' => 'notifications',

'endpoint' => null,

'identifier' => null

],

[

1 => 'version',

2 => 'endpoint',

3 => 'identifier'

]

));

$this->addRoute('notifications/api-plural', new Zend_Controller_Router_Route(

'notifications/api/:version/:endpoint',

[

'module' => 'notifications',

'controller' => 'api',

'action' => 'index'

]

));

$this->addRoute('notifications/api-single', new Zend_Controller_Router_Route(

'notifications/api/:version/:endpoint/:identifier',

[

'module' => 'notifications',

'controller' => 'api',

'action' => 'index'

]

));

Note that Zend processes routes in reverse order. So notifications/api-single will be processed first. It cannot match without an identifier, because there is no forward slash in our endpoint names. notifications/api-plural on the other hand cannot match with an identifier, because notifications/api-single is processed first. 😉

nilmerg · 2025-08-26T07:55:45Z

application/controllers/ApiController.php

+     */
+    public function indexAction(): never
+    {
+        $this->assertPermission('notifications/api/v1');


I know the issues requires this. But now I'm not sure anymore, whether it makes sense to have the api version in the permission's name. Why would someone, permitted to use v1, not be able to use v2?

Though, do not change anything yet. Leave this for later.

nilmerg · 2025-08-26T08:38:09Z

application/controllers/ApiController.php

+     * @throws HttpBadRequestException If the request is not valid.
+     * @throws SecurityException
+     * @throws HttpException|HttpNotFoundException
+     * @throws Zend_Controller_Request_Exception


The return type is missing

nilmerg · 2025-08-26T08:39:14Z

application/controllers/ApiController.php

+        $version = StringHelper::cname($params['version'] ?? null, '-');
+        $endpoint = StringHelper::cname($params['endpoint'] ?? null, '-');


Please use ipl-stdlib's Str::camel here.

nilmerg · 2025-08-26T08:40:16Z

application/controllers/ApiController.php

+        if (empty($version) || empty($endpoint)) {
+            throw new HttpException(404, "Version and endpoint are required parameters.");
+        }


The routes I suggested should verify this and make this check obsolete.

nilmerg · 2025-08-26T08:41:17Z

application/controllers/ApiController.php

+            throw new HttpException(404, "Version and endpoint are required parameters.");
+        }
+
+        $module = ($moduleName !== null) ? 'Module\\' . StringHelper::cname($moduleName, '-') . '\\' : '';


None of our modules use dashes in their name.

nilmerg · 2025-08-26T08:42:55Z

application/controllers/ApiController.php

+        }
+
+        $module = ($moduleName !== null) ? 'Module\\' . StringHelper::cname($moduleName, '-') . '\\' : '';
+        $className = sprintf('Icinga\\%sApi\\%s\\%s', $module, $version, $endpoint);


I like that this may already be compatible with an Icinga Web API 😃

nilmerg · 2025-08-26T08:44:43Z

application/controllers/ApiController.php

+        $className = sprintf('Icinga\\%sApi\\%s\\%s', $module, $version, $endpoint);
+
+        // Check if the required class and method are available and valid
+        if (! class_exists($className) || (new ReflectionClass($className))->isAbstract()) {


Not sure why the abstract check is required. If an abstract class matches an endpoint, this should result in a server error, not a not found.

nilmerg · 2025-08-26T09:00:44Z

application/controllers/ApiController.php

+        // TODO: move this to an api core or version class?
+        $parsedMethodName = ($method === 'GET' && empty($identifier)) ? $methodName . 'Any' : $methodName;
+
+        if (! in_array($parsedMethodName, get_class_methods($className))) {
+            if ($method === 'GET' && in_array($methodName, get_class_methods($className))) {
+                $parsedMethodName = $methodName;
+            } else {
+                throw new HttpException(405, "Method $method does not exist.");
+            }
+        }
+
+        // Choose the correct constructor call based on the endpoint
+        if (in_array($method, ['POST', 'PUT'])) {
+            $data = $this->getValidatedJsonContent($request);
+            (new $className($request, $response))->$parsedMethodName($data);
+        } else {
+            (new $className($request, $response))->$parsedMethodName();
+        }


Please do this without depending on any Zend objects. Including request and response.

Once you've identified a class using the endpoint, instantiate it and interact with it by expecting it to be of type RequestHandlerInterface.

The identifier should be part of the request object in the form of an attribute (The last paragraph of the linked section).

The end result should be that this controller is the last part in the chain that is built on top of Zend routing and dispatching. Everything else is PSR7/15 compliant and can then easily migrated to an alternative in the future.

nilmerg · 2025-08-26T09:11:02Z

library/Notifications/Api/V1/ApiV1.php

+        $this->version = 'v1';
+        $this->validateIdentifier();
+        $method = $this->getRequest()->getMethod();
+        $filterStr = Url::fromRequest()->getQueryString();


Get the query string from the request please, do not use a url object for this. Once this is PSR15 compliant, everything should be inferred from the request. Singletons are not an option.

nilmerg · 2025-08-26T09:14:23Z

Oh, and I got the postgres tests working in my environment. Please get back to me for this.

ICINGA_NOTIFICATIONS_SCHEMA=/path/to/notifications/schema.sql ICINGAWEB_PATH=/icingaweb2 /usr/share/icinga-php/ipl/vendor/bin/phpunit --bootstrap test/php/bootstrap.php Note that you will need a database for this, and propagate this via env as well: * Name | Description * ----------------- | ------------------------ * *_TESTDB | The database to use * *_TESTDB_HOST | The server to connect to * *_TESTDB_PORT | The port to connect to * *_TESTDB_USER | The user to connect with * *_TESTDB_PASSWORD | The password of the user

application/controllers/ApiController.php

library/Notifications/Api/ApiCore.php

application/controllers/ApiController.php

library/Notifications/Api/ApiCore.php

sukhwinder33445 · 2025-09-29T07:26:46Z

library/Notifications/Api/V1/ApiV1.php

+            HttpMethod::POST => $this->post($identifier, $this->getValidRequestBody($request)),
+            HttpMethod::GET => $this->get($identifier, $filterStr),
+            HttpMethod::DELETE => $this->delete($identifier),
+            default => throw new HttpBadRequestException("Invalid request: This case shouldn't be reachable."),


Remove this default case, please.

sukhwinder33445 · 2025-09-29T07:33:15Z

library/Notifications/Api/V1/ApiV1.php

+        }
+        if ($httpMethod === HttpMethod::GET && ! empty($identifier) && ! empty($filterStr)) {
+            throw new HttpBadRequestException(
+                'Invalid request: ' . $httpMethod->uppercase() . ' with identifier and query parameters,'


I would recommend using sprintf() instead.

sukhwinder33445 · 2025-09-29T07:36:16Z

library/Notifications/Api/V1/Channels.php

+                'channel_id' => 'ch.id',
+                'id' => 'ch.external_uuid',


Please correct the indentation.

sukhwinder33445 · 2025-09-29T07:40:54Z

library/Notifications/Api/V1/Channels.php

+     * @throws HttpNotFoundException
+     * @throws JsonEncodeException
+     */
+    public function get(?string $identifier, string $filterStr): array


Please rename the parameter to $queryFilter or $filter. The data type already specifies that it must be a string.

sukhwinder33445 · 2025-09-29T07:41:53Z

library/Notifications/Api/V1/ApiV1.php

+            HttpMethod::PUT => $this->put($identifier, $this->getValidRequestBody($request)),
+            HttpMethod::POST => $this->post($identifier, $this->getValidRequestBody($request)),
+            HttpMethod::GET => $this->get($identifier, $filterStr),
+            HttpMethod::DELETE => $this->delete($identifier),


Please correct the indentation.

sukhwinder33445 · 2025-09-29T08:14:05Z

library/Notifications/Api/V1/Contacts.php

+                'contact_id' => 'co.id',
+                'id' => 'co.external_uuid',
+                'full_name',
+                'username',
+                'default_channel' => 'ch.external_uuid',


Please correct the indentation.

sukhwinder33445 · 2025-09-29T08:14:23Z

library/Notifications/Api/V1/Contacts.php

+            ->joinLeft('contact_address ca', 'ca.contact_id = co.id')
+            ->joinLeft('channel ch', 'ch.id = co.default_channel_id')
+            ->where(['co.deleted = ?' => 'n']);
+        if ($identifier === null) {


Add a new line please.

sukhwinder33445 · 2025-09-29T08:23:36Z

library/Notifications/Api/V1/Contacts.php

+                $this->assertUniqueUsername($requestBody['username'], $contactId);
+            }
+
+            if (! $channelID = Channels::getChannelId($requestBody['default_channel'])) {


Please initialize the variable before the condition, as it is used outside the scope of the condition.

sukhwinder33445 · 2025-09-29T08:25:13Z

library/Notifications/Api/V1/Contacts.php

+                'contact_id'    => $contactId,
+                'type'          => $type,
+                'address'       => $address,
+                'changed_at'            => (int) (new DateTime())->format("Uv"),


Fix the indentation please.

sukhwinder33445 · 2025-09-29T08:41:46Z

library/Notifications/Api/V1/ApiV1.php

+        $identifier = $request->getAttribute('identifier');
+        $filterStr = $request->getUri()->getQuery();
+
+        $responseData = match ($request->getAttribute('httpMethod')) {


I think it's a good idea for the methods to return a ResponseInterface instead of an array.

This reverts commit e4dd073.

Jan-Schuppik requested a review from nilmerg August 22, 2025 13:51

Jan-Schuppik self-assigned this Aug 22, 2025

cla-bot bot added the cla/signed CLA is signed by all contributors of a PR label Aug 22, 2025

Jan-Schuppik force-pushed the feature/http-api-new-approach branch from 9a3a6aa to aa2b625 Compare August 25, 2025 12:48

nilmerg requested changes Aug 26, 2025

View reviewed changes

This was referenced Sep 3, 2025

Add column external_uuid to contact/contactgroup table Icinga/icinga-notifications#216

Open

HTTP API to configure contacts and contactgroups #199

Closed

Jan-Schuppik force-pushed the feature/http-api-new-approach branch from f53b374 to 1705125 Compare September 3, 2025 10:49

Jan-Schuppik and others added 17 commits September 3, 2025 12:51

Add: column external_uuid & missing column changed_at

6132474

Introduce: PSR Logger

f67dc8c

Fix: test-setup for MySQL compatibility (PostgreSQL tests still failing)

efce1f9

Adjust: unit tests

be015b6

Add: route for new api controller

e6fac6a

Introduce: new API srtucture (starting with Contact GET)

47dcb8e

Add: initial openapi docs

bed7f05

Adjust: give the request object to ApiCore

a1e1d4f

Fix: lint-errors & moduleName fetching

ed824d1

Remove: Icinga Web 2 BaseTestCase dependency

5c15181

Adjust: add small review suggestions

f3999ce

Rework: implements psr-15 RequestHandlerInterface

6bd5cbc

Adjust: api-version handling

0dc1def

Fix: request validation & plural-GET result name & test permissions

5ee193a

Adjust: openapi documentation creating & storing

9116e17

Fix: Psr-Logger exception-handling

fe816f8

Jan-Schuppik force-pushed the feature/http-api-new-approach branch from 1705125 to fe816f8 Compare September 3, 2025 10:58

Jan-Schuppik added 3 commits September 3, 2025 13:22

Introduce: PUT method handling

64912d8

Adjust: Openapi Attributes (+ fix strings)

7a86078

Introduce: POST method handling

3510235

Jan-Schuppik added 3 commits September 26, 2025 10:53

Fix: mysql external_uuid db type

3f349d0

Fix: cases of class-call in dispatching

76eb05b

Adjust: response header content-type

da665ca

Jan-Schuppik force-pushed the feature/http-api-new-approach branch from 30b0b1b to da665ca Compare September 26, 2025 09:01

Fix: Code-Sniffer Errors

22cc2c2

sukhwinder33445 reviewed Sep 26, 2025

View reviewed changes

Jan-Schuppik added 3 commits September 26, 2025 13:15

Adjust: cleanup row preparation for output

439c88b

Adjust: improve the php-docs

dc36e1c

Adjust: cleanup code & set response-header if not provided

1792eb3

sukhwinder33445 requested changes Sep 29, 2025

View reviewed changes

Jan-Schuppik and others added 20 commits September 29, 2025 12:23

Adjust: return response instead of assoc array in endpoint-methods

5b1dda2

Fix: change unsuitable names

bf626f2

Fix: correct indentations

b602287

Adjust: use sprintf() to cleanup strings

a4a8b93

Remove: TODOs

93b1f96

Adjust: identifier-check in post-methods

8b0757b

Fix: scope of variables initialized in if-condition

efaebe2

Fix: add spacing to improve readability

6a7294b

Fix: IDE warnings

f5978f7

Adjust: use database via singleton instead of initialize variables

bd5722e

Fix: exceeding line

7033717

Fix: unit-tests for new database-trait

3edeb19

Fix: scope of a variable

8b95b09

Adjust: make unit-tests independent

fa3c98e

Fix: use getConnection() (need ipl-sql shared-test-databases updated)

bb49065

Fix: unit-test errors caused by databases

e4dd073

Revert "Fix: unit-test errors caused by databases"

98f37f7

This reverts commit e4dd073.

Introduce and use new ApiTestBackends data provider

2de692e

Fix: unit-tests according to new data provider

5a419f5

Fix: Code-Sniffer Errors

c381c9f

		$version = StringHelper::cname($params['version'] ?? null, '-');
		$endpoint = StringHelper::cname($params['endpoint'] ?? null, '-');

Feature/http api new approach #348

Are you sure you want to change the base?

Feature/http api new approach #348

Uh oh!

Conversation

Jan-Schuppik commented Aug 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Resolves:

require:

Uh oh!

nilmerg left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nilmerg commented Aug 26, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Jan-Schuppik commented Aug 22, 2025 •

edited

Loading