Back to overview

RESTful API

Add it on-the-fly to your HumHub by activating it in the Modules menu! ("Administration -> Modules")


RESTful API

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.

Requirements

Available endpoints

You can find a full list of available API endpoints in the Usage manual

Installation

After installation make sure to set an API key at Administration -> Modules -> Installed -> Rest API.

Available Endpoints

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/htmlcontains HTML rendered documentations for all available API endpoints.

Swagger / OpenAPI 3.0.0

You can find Swagger documentation files in the /docs/swagger directory of this module.

PostMan

/docs/postman contains a PostMan collection with all available requests.

API development

Documentation

To completely adapt the API documentation after a change, the following steps are necessary.

Swagger

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

PostMan

Also add examples to the PostMan API request collection located in the folder: /docs/postman.

Other module support

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';
    }
}

0.6.1 (May 06, 2022)

  • Fix #91: Use Content-Type "application/json" for endpoint auth/login in request

0.6.0 (May 26, 2022)

  • Enh #41: Add Comment API endpoints

0.5.1 (May 16, 2022)

  • Fix #88: Increase min version for new field Content::locked_comments

0.5.0 (May 6, 2022)

  • Enh #85: Allow update of Content Topics
  • Enh #85: Allow update of Content Metadata (Visibility, Archived, Pinned)
  • Enh #70: Content: Add sorting option

0.4.3 (February 1, 2022)

  • Enh #73: Added "mustChangePassword" flag for users created using the API
  • Enh: Don't provide auth token for disabled users on REST module side

0.4.2 (January 31, 2022)

  • Enh #72: Added Visibility as Content MetaData

0.4.1 (January 25, 2022)

  • Enh #74: Response space container ID
  • Enh #75: Attach files to content

0.4.0 (January 19, 2022)

  • Enh #33: Move endpoints to external modules
  • Fix #60: Cleanup code for prepare params
  • Enh #86: Docs for polls module
  • Fix #67: Update docs for container(space/user) tags
  • Enh #74: Response space container ID
  • Enh #75: Attach files to content

0.3.1 (Unreleased)

  • Enh: Use controller config for not intercepted actions
  • Fix #57: Use getBodyParam() to extract the 'role' body parameter for the space membership

0.3.0 (February 22, 2021)

  • Fix #51: Remove group.space_id for compatible with Humhub 1.8

0.2.1 (February 17, 2021)

  • Enh #45: Files Endpoint - Don’t require target folder id to create root automatically

0.2.0-beta.1 (November 23, 2020)

  • Enh: New Endpoints for Mail module
  • Enh: Added permission checks for regular user access
  • Fix #42: Activity Module Endpoint
  • Fix #43: Swagger doc is incorrect for user "display_name" for User endpoints
  • Fix: Renamed "/like/findByRecord" endpoint to "/like/find-by-object"

0.1.4 (October 13, 2020)

  • Enh: User new endpoints, find-by-username and find-by-email
  • Enh: Added current User details endpoint

0.1.3 (August 5, 2020)

  • Fix: HumHub 1.6 compatibility issues

0.1.2 (January 31, 2020)

  • Enh: Added User group endpoint

0.1.1 (January 17, 2020)

  • Initial release in marketplace
  • Chg: Removed 'members' attribute from 'Space' output object
  • Enh: Added Space Membership Endpoint

0.1.0 (20 December, 2019)

  • Initial release in marketplace
  • Enh: Various new endpoints and features

0.0.1 (Unrelased)

Initial release

Version:
0.6.1 (released 3 months ago)

Publisher:
HumHub GmbH & Co. KG

Website:
https://github.com/humhub/rest

Compatibility:
HumHub 1.10 - Latest





HumHub Cloud

Free
Install it on-the-fly at the admin panel
in your HumHub hosting instance


HumHub Self-Hosted

Free
Install it on-the-fly at the admin panel
in your HumHub installation