# 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](io/aalam/common/HttpRequest.rst)
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](io/aalam/common/Role.rst) 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