# URL Routes

Routes registration
-------------------
The application can register its list of HTTP APIs in
[Callback.routes()](io/aalam/common/Callbacks.rst) callback.
`Callback.routes()` method is called with the
[Mapper](io/aalam/common/router/Mapper.rst) object and all the urls for
an application must be connected to this mapper through this callback.

**Every URL should start with `/<provider-code>/<app-code>/`**

Where `<provider-code>` and the `<app-code>` will be the application's provider
code and app code registered with the Aalam developer portal. Any URL
that violates the above condition cannot not be accessed at all.

Following are some examples on the URL formats.

- Static URL with no dynamic arguments are like below. Only the requests
matching this exact format will be routed to this handler
    ```
    /aalam/base/users
    ```
- If a url has a dynamic argument, the dynamic arguments should be enclosed in
{}, the name of the argument will be passed as a parameter to the *action* of
the handler for this URL. Ex.
    ```
    /aalam/base/user/{user_email_id}
    ```
  In here, the `{user_email_id}` is a dynamic argument and the handler method
  will be passed with this argument. The above URL will match for URL like,

    ```
    /aalam/base/user/user1@test.test
    /aalam/base/user/self
    ```

- If a URL has many dynamic arguments, the *action* of the handler will be
passed with order of their appearence. Ex.
    ```
    /aalam/base/user/{email_id}/status/{status}/mark
    ```
  In the above example, `email_id` and `status` are passed to the *action*
method in the order of the appearence. The action method can be defined like
    ```
    public Object markUserStatus(HttpRequest request, String email_id, String status):
        # Actual logic here
        pass
    ```

- The first parameter of the action handler is the
[HttpRequest](io/aalam/common/HttpRequest.rst) object. Detail related to the
request like the input content, the authentication parameters, authorization
parameters, request url, etc all can accessed using this object.

- The action handler is expected to return an Object. If the return value is
non-null, then it should either be

> - null object, if it wishes to send an empty `200 OK` response
> - Object of [HttpResponse](io/aalam/common/HttpResponse.rst)
> - Object of [StatusTuple](io/aalam/common/StatusTuple.rst)
> - Object of [Serializer](io/aalam/common/Serializer.rst)

- The action handler can throw a [HttpException](io/aalam/common/HttpException.rst)
if it wishes to abort processing on any error with an appropriate status code.