Warning: Beta version - API may change in the next releases!
The REST API module provides a generic interface to various subsystems of the HumHub platform.
You can find a full list of available API endpoints in the Usage manual
After installation make sure to set an API key at Administration -> Modules -> Installed -> Rest API
.
Following RESTful API endpoints are available.
Base URL:
The base url for all APIs is: https://yourhost/api/v1/
Core APIs:
Module APIs
The folder /docs/html
contains HTML rendered documentations for all available API endpoints.
You can find Swagger documentation files in the /docs/swagger
directory of this module.
/docs/postman
contains a PostMan collection with all available requests.
To completely adapt the API documentation after a change, the following steps are necessary.
The Swagger documentation is located in the folder /docs/swagger
, you need to rebuild the html documentation
at /docs/html
which is based on the Swagger YAML files.
To create a HTML documentation you need to install the redoc-cli
NPM package.
Build HTML documentation:
cd docs/swagger
./build-all.sh
Also add examples to the PostMan API request collection located in the folder: /docs/postman
.
To append endpoints from another module:
1) Add event in the file config.php
of your module the following line:
['class' => 'humhub\modules\rest\Module', 'event' => 'restApiAddRules', 'callback' => ['humhub\modules\your_module\Events', 'onRestApiAddRules']],
2) Implement humhub\modules\your_module\Events::onRestApiAddRules
like this:
public static function onRestApiAddRules()
{
/* @var humhub\modules\rest\Module $restModule */
$restModule = Yii::$app->getModule('rest');
$restModule->addRules([
['pattern' => 'your_module/<objectId:\d+>/user/<userId:\d+>', 'route' => 'your_module/rest/user/add', 'verb' => 'POST'],
...
]);
}
3) Create a new controller, for example, here protected/modules/your_module/controllers/rest/UserController.php
:
namespace humhub\modules\your_module\controllers\rest;
use humhub\modules\rest\components\BaseController;
class UserController extends BaseController
{
public function actionAdd($messageId, $userId)
{
return [...];
}
}
4) Modify your module initialization in order to avoid errors on CLI mode:
public function init()
{
parent::init();
if (Yii::$app instanceof \humhub\components\console\Application) {
// Prevents the Yii HelpCommand from crawling all web controllers and possibly throwing errors at REST endpoints if the REST module is not available.
$this->controllerNamespace = 'your_module/commands';
}
}
Initial release