REST API overview

[]

This document is an overview of the four basic areas of the REST API available out-of-the-box and how to extend them. It is not meant to be a reference documentation.

All four handlers are mapped together in the ExpressAdapter.ts script, in the factory lambda function, but their implementations are distributed across several files.

MiddlewareApi

Purpose

MiddlewareApi.ts is the most generic part of the API and the most common place to add new endpoints. Out-of-the-box, it supports endpoints for the Media Room.

Authorization handling

Different middleware endpoints handle authorization in a different way.

1. Authorization is handled by HCMS. Most endpoints do not need to handle authorization themselves, because they just pass the same JWT token they received to the HCMS. Forwarding the token is done by the utility function nonPrivilegedHcms, which creates an appropriate HCMS HTTP client.

2. The endpoint invokes a privileged HCMS request, like /media/schema/descriptive/:language? (that reads the full schema with language localization).

3. The endpoint handles authorization by itself, using makeJwtValidator:

import { makeJwtValidator } from './JwtValidation';

const jwtValidator = makeJwtValidator(config.jwt);
this._router.post(
  "/custom/new/endpoint",
  jwtValidator,
  async (req, res, next) => {
    res.send({TODO:'Implement'});
  }
);

DataApi

Purpose

DataApi.ts provides basic data to the frontend. Out-of-the-box, the Data API contains some basic image manipulation endpoints (like for generating splash and icon images) and a PWA manifest generator.

Authorization handling

Usually, the media data is publicly available and the access to it does not require any authorization.

However, the most important endpoint,/data/config.json can be used both authorized and unauthorized, with slightly different results. For this reason, it handles its own authorization and this code can be used as a sample for an endpoint with similar semantics.

Notes on implementation

/data/config.json is the entry point for the frontend integration, because it provides the frontend with all necessary links (various API parts) and configuration.

Authentication API

Purpose

This API handles authentication (login, logout, refresh), self-registration, password reset, etc.

Notes on implementation

Unlike the other APIs, the authentication API is designed to be used even without the whole rest of the HCMS Client. For this reason, the actual implementation of it exists as a separate module. The <code>AuthenticationApi.ts</code> only serves as an adapter to pass configuration and the HCMS Client to that implementation module.

For more information on the authentication API, please refer to its reference documentation

Module configuration API

Purpose

Endpoints in this API pass the portal configuration to each module, plus provide a possibility to upload and download simple images (used for theming: icons, background).

Authorization handling

In the <code>ModuleConfigApi.ts</code>, the ModuleConfigApi class provides the correct path and makes sure that all endpoints are available only for the authenticated (logged-in) users via makeJwtValidator.

Notes on implementation

The API is actually implemented by an instance of the interface PortalConfigProvider of the ModuleConfigApi class. All endpoints are created through the method configMgmtRouter in the <code>PortalConfigProvider.ts</code> and the module configration handlers are shared too, but the image endpoints depend completely on the subclass.