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 PKG-INFO.

If an application does not want any of its API to be hooked, it can list those in the ‘restrict’ section of it’s PKG-INFO

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 authentication 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 the type of hooks pass some data to the callback which can be accessed by

hook_data = request.json

hook_data above will be a dictionary whose format varies with the type of hook.

‘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.json 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 to display the apps in the front page for a user uses this feature. 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.json 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