Project

General

Profile

Wiki » Documentation » Installation Configuration and Administration Guide » Administration REST API »

Hooks Management API

This API provides a way to control the external hooks managed by the server, ranging from listing all available hooks to initializing or terminating individual ones. It provides a way to inspect the state of each server hook that implements the ExternalHook interface.

The work on this feature was implemented in #10591.

Configuration

Hooks Management API is a sub-module of Administration_REST_API. In order to enable the hooks support in FWD, the global REST API must be enabled. Please see the REST API Setup/Configuration. There are no additional requirements for this sub-module.

Add Permissions for the Session Admin API

In order to have access to the session administration API, you need to add permissions. This is done via ACLs in the following manner:

<node class="container" name="security">
  <node class="container" name="acl">
    <node class="container" name="webservice">
      <node class="container" name="000100">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/hooks"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000200">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:GET:/admin/hooks/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000300">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:PUT:/admin/hooks/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
      <node class="container" name="000400">
        <node class="resource" name="resource-instance">
          <node-attribute name="reference" value="ADMIN:DELETE:/admin/hooks/.*"/>
          <node-attribute name="reftype" value="FALSE"/>
        </node>
        <node class="webServiceRights" name="rights">
          <node-attribute name="allow" value="true"/>
        </node>
        <node class="strings" name="subjects">
          <node-attribute name="values" value="restAdmin"/>
        </node>
      </node>
    </node>
  </node>
</node>

For the definition of admin-rest FWD user, please see the REST API Setup/Configuration.

By setting these, you will allow requests of the following types at the following paths:

  • GET at /admin/hooks, which is used for listing all external hooks available on the server.
  • GET at /admin/hooks/<className>, for retrieving information about the given hook.
  • PUT at /admin/hooks/<className>, which is used to initialize (start) the given external hook.
  • DELETE at /admin/hooks/<className>, which is used to terminate (stop) the given external hook.

Double-check the paths leading to the options in order for the server to read them correctly!

API routes

The Session Management API has the following capabilities:
  • Login: the login and logout operations are provided by the main module. For an example of how this is achieved, take a look at REST Admin Authentication.
  • List all hooks: by performing a GET request at /admin/hooks. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON array containing all registered external hooks, each with className and initialized properties.
    • Example:
  • Get a single hook: by performing a GET request at /admin/hooks/<className>. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON object containing information about the hook with className and initialized properties, or an error if the hook does not exist.
    • Example:
  • Initialize a hook: by performing a PUT request at /admin/hooks/<className>. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON message indicating success or failure.
    • Example of success:
    • Example of failure:
  • Terminate a hook: by performing a DELETE request at /admin/hooks/<className>. The header must contain the FwdSessionId token. No body is required.
    • The response body will be a JSON message indicating success or failure.
    • Example of success:
    • Example of failure:
Note:
  • <className> corresponds to the fully qualified class name of the hook.
  • Use GET /admin/hooks to retrieve all available hooks and their current initialization status before performing PUT or DELETE operations.
  • Error responses will return HTTP 400 for invalid paths, 404 for non-existent hooks, or 409 for conflicts (already initialized or not initialized).

© 2024-2025 Golden Code Development Corporation. ALL RIGHTS RESERVED.