Hooks

If an application wishes to receive notifications when a URL of another application is requested, hooks are the way.

For example if an application wishes to receive notifications every time a contact is created, it can hook the base application API PUT /aalam/base/contacts

The hooks that an application wants can be listed in the ‘hooks’ section of it’s pom.xml.

If an application does not want any of it’s API to be hooked, it can list those in the ‘restrict’ section in the pom.xml

A hook callback method should be public static method in a public class.

Every hook callback will be called with the request object of the hook. The request object holds all the information of the hooked API. The method and the url parameters in the request object gives information about the hooked API.

The request object also holds the authentication information about the requester of this URL. One can use the Role APIs and the authorization APIs to validate the requester. For example, applications can hook /aalam/base to return a hook-input data customized for the user.

Hooks are two types

• ‘B’ Hook
• ‘A’ Hook

Both types of hooks pass some data along with the request object passed to the callback. The format of the data differs with the hook type. This data will be in json format.

Data returned from the hook callbacks are either null or should be JsonSerializer object. Hook callback usually returns data only in ‘B’ Hooks.

‘B’ Hooks

‘B’ stands for Before. If an application has hooked an API with this type, it will receive a callback before the API is even processed.

request data will be of the following format

{
    "type": "B",  # Always 'B'
    "headers": "A dictionary with all the original request's headers and values",
    "params": "A dictionary with all the original request's parameters",
    "data": "The input data sent with the original request"
}

‘B’ hooks are more special as they give a provision for the hooker to send some data to hooked API which that API can access in its request.hook_data. This will be interesting only when the hookee defines an input data specification, which the hookers can follow.

The base application uses this feature to display the apps in the front page for a user. Refer base application documentation for more information.

‘A’ Hooks

‘A’ stands for After. If an application has hooked an API with this type, it will receive a callback after the API is processed by its action handler.

request data will be of the following format

{
    "type": "A",  # Always 'A'
    "params": "A dictionary with all the original request's parameters",
    "status": "The response status code that the original URL's
               action handler returned",
    "data": "The serialized output data the the original URL's has
             set in the response"
}

This type of hook is just for notification process, the hooker has no influence on the response set by the hookee