Adding a new custom APi endpoint?

[TOA-Anakin]

Greetings, how do I add a new custom API endpoint? What am I missing?

Default search and record API endpoints are working fine but the Swagger UI page renders this error:

and the custom API endpoint /api/v1/hello is NOT working as well.

module/CustomApi/Module.php:

namespace CustomApi;

class Module
{
    /**
     * Get module configuration
     *
     * @return array
     */
    public function getConfig()
    {
        return include __DIR__ . '/config/module.config.php';
    }
}

module/CustomApi/config/module.config.php

<?php

namespace CustomApi\Module\Configuration;

$config = [
    'controllers' => [
        'factories' => [
            'CustomApi\Controller\HelloController' => 'CustomApi\Controller\HelloControllerFactory',
        ],
        'aliases' => [
            'HelloApi' => 'CustomApi\Controller\HelloController',
        ],
    ],
    'vufind_api' => [
        'register_controllers' => [
            \CustomApi\Controller\HelloController::class,
        ],
    ],
    'router' => [
        'routes' => [
            'helloApiv1' => [
                'type' => 'Laminas\Router\Http\Literal',
                'verb' => 'get,options',
                'options' => [
                    'route' => '/api/v1/hello',
                    'defaults' => [
                        'controller' => 'HelloApi',
                        'action' => 'hello',
                    ],
                ],
            ],
        ],
    ],
];

return $config;

module/CustomApi/src/CustomApi/Controller/HelloController.php

namespace CustomApi\Controller;

use VuFindApi\Controller\ApiInterface;
use VuFindApi\Controller\ApiTrait;

class HelloController extends \VuFind\Controller\AbstractBase implements ApiInterface
{
    use ApiTrait;

    /**
     * Hello action
     *
     * @return \Laminas\Http\Response
     */
    public function helloAction()
    {
        $this->disableSessionWrites();

        $this->determineOutputMode();

        $response = [
            'message' => 'Hello World',
            'timestamp' => date('Y-m-d H:i:s'),
        ];

        return $this->output($response, self::STATUS_OK);
    }

    /**
     * Get API specification JSON fragment for services provided by the controller
     *
     * @return string
     */
    public function getApiSpecFragment()
    {
        $spec = [
            'paths' => [
                '/hello' => [
                    'get' => [
                        'summary' => 'Hello World endpoint',
                        'description' => 'Returns a Hello World message',
                        'tags' => ['hello'],
                        'responses' => [
                            '200' => [
                                'description' => 'Success response',
                                'content' => [
                                    'application/json' => [
                                        'schema' => [
                                            'type' => 'object',
                                            'properties' => [
                                                'status' => [
                                                    'type' => 'string',
                                                    'example' => 'OK'
                                                ],
                                                'message' => [
                                                    'type' => 'string',
                                                    'example' => 'Hello World'
                                                ],
                                                'timestamp' => [
                                                    'type' => 'string',
                                                    'example' => '2025-07-28 12:00:00'
                                                ]
                                            ]
                                        ]
                                    ]
                                ]
                            ]
                        ]
                    ]
                ]
            ]
        ];

        return json_encode($spec);
    }
}

module/CustomApi/src/CustomApi/Controller/HelloControllerFactory.php

namespace CustomApi\Controller;

use Laminas\ServiceManager\Exception\ServiceNotCreatedException;
use Laminas\ServiceManager\Exception\ServiceNotFoundException;
use Laminas\ServiceManager\Factory\FactoryInterface;
use Psr\Container\ContainerExceptionInterface as ContainerException;
use Psr\Container\ContainerInterface;

class HelloControllerFactory implements FactoryInterface
{
    /**
     * Create an object
     *
     * @param ContainerInterface $container     Service manager
     * @param string             $requestedName Service being created
     * @param null|array         $options       Extra options (optional)
     *
     * @return object
     *
     * @throws ServiceNotFoundException if unable to resolve the service.
     * @throws ServiceNotCreatedException if an exception is raised when
     * creating a service.
     * @throws ContainerException&\Throwable if any other error occurs
     */
    public function __invoke(
        ContainerInterface $container,
        $requestedName,
        ?array $options = null
    ) {
        if (!empty($options)) {
            throw new \Exception('Unexpected options sent to factory.');
        }

        return new $requestedName($container);
    }
}

config/application.config.php

<?php

require __DIR__ . '/constants.config.php';

// Set up modules:
$modules = [
    'Laminas\Cache',
    'Laminas\Cache\Storage\Adapter\BlackHole',
    'Laminas\Cache\Storage\Adapter\Filesystem',
    'Laminas\Cache\Storage\Adapter\Memcached',
    'Laminas\Cache\Storage\Adapter\Memory',
    'Laminas\Form',
    'Laminas\Router',
    'LmcRbacMvc',
    'Laminas\I18n',
    'Laminas\Mvc\I18n',
    'SlmLocale',
    'VuFindTheme',
    'VuFindSearch',
    'VuFind',
    'VuFindAdmin',
    'CustomApi',     // <- I have added it here
    'VuFindApi',
];

// ...

local/project1/config/vufind/permissions.ini

; ...

[api.v1.allowAll]
require = ANY
permission[] = access.api.v1.search
permission[] = access.api.v1.record
permission[] = access.api.v1.hello
ipRange[] = 0.0.0.0-255.255.255.255

local/project1/config/vufind/searches.ini

; ...

; This section controls default behavior of the Search API.
[API]
; These permissions must be defined in permissions.ini to grant access to the API:
recordAccessPermission = access.api.v1.record
searchAccessPermission = access.api.v1.search

[demiankatz]

@TOA-Anakin, thanks for sharing so much detail; this should be helpful for troubleshooting!

In general, your approach looks reasonable to me, but a few initial questions/suggestions:

1.) Have you cleared out your $VUFIND_LOCAL_DIR/cache/configs directory after setting this up? Sometimes the configuration cache can get in the way of new modules appearing right away. Turning on development mode could also help by disabling some layers of caching.

2.) I generally advice against making changes to application.config.php -- you should be able to use the VUFIND_LOCAL_MODULES environment variable in $VUFIND_LOCAL_DIR/httpd-vufind.conf to register local custom modules without editing code.

3.) Which version of the code are you using? If you're on a recent dev branch, you may need to register your custom module in the autoload configuration of composer.json.local as well. You can use the install.php tool to create and register a new custom module if that's easier than doing it manually.

I hope this is some help, but please let me know if you are still stuck!

[TOA-Anakin]

Thank you @demiankatz youre the best.

I added the path to my custom module in composer.json.local, ran composer dump-autoload, registered the custom module with VUFIND_LOCAL_MODULES, restarted the server and now it is finally working.

[demiankatz]

Ha, that meme perfectly captures the experience of getting up and running with Laminas for the first time. Fortunately, once the baseline is in place, it's a lot less painful after that. In any case, glad I could help. I'll mark this conversation as closed since we found a resolution, but please feel free to open another or reopen if needed.