Http Module

The http module is used for all basic AJAX calls in Hibiki HTML. It allows you to call AJAX handlers and returns their results.

The module is named http, but it handles both http and https requests!

Here are some sample http module calls:

  # simple GET
  GET /api/test-1
  
  # a relative URL
  GET relative/url.html?test=1
  
  # POST to a remote resource
  POST https://remoteserver.any.com/api/test-post
  
  # 'GET' can be omitted for URLs that start with http, https, or //
  https://testapi.hibikihtml.com/api/random-number
  
  # adding a parameter x=55, will be added to URL
  # e.g. equivalent to /api/test-1?y=22&x=55
  GET /api/test-1?y=22(x=55)
  
  # POST, with url encoded parameters
  POST /api/test-post(user={id: 55, name: 'mike'}, access_code='A55', @enc='url')

Each call can be configured by passing special @ parameters. Global configuration is done through the httpConfig key of the global <hibiki-config>.

Sometimes you need special http options for a particular host (e.g. a REST endpoint that requires special headers or CSRF handling). You can set that up easily by adding an addition HTTP module (see Additional HTTP Modules below).

Any non @ parameter is considered data and will be passed to the AJAX handler. Here are the special parameters that all http calls accept. See the fetch() API documentation.

These ‘@’ params are used for one-off overrides of individual requests. If you always want to send a particular header or set a special init setting, it can often be easier to specify the value in the HttpConfig object (see below).

To make an AJAX handler call with a dynamic URL, you need to use the callhandler statement. It takes the same parameters (above), but additionally it takes two more @url and @module:

Here’s some examples:

callhandler(@url="https://testapi.hibikihtml.com/api/get-color-1");

@handler_name = 'get-color-' + $.colornum;
callhandler(@url="https://testapi.hibikihtml.com/api/" + @handler_name)

# hibiki module call, equivalent to //@hibiki/sleep(ms=1000);
callhandler(@module="hibiki", @url="/sleep", ms=1000);

Http Config is set as the httpConfig key of the global <hibiki-config>:

<template hibiki>
  <hibiki-config>
  {
     ... other config options ...
     "httpConfig": { ... http options ... }
  }
  </hibiki-config>
</template>

If you are making requests to multiple endpoints which require different headers, CSRF settings, or fetchInit parameters, you can configure additional HTTP modules.

Here’s an example config that sets up a module named ‘app’ that always includes an ‘X-UserId’ header set to a hibikiexpr of ‘$.userid’, a static header (X-Domain-Id), and a special CSRF configuration. Notes:

• The name of the module is the key under “modules”, in this case “app”.
• The “type” key is required. For HTTP modules it must be set to “http”.
• The rest of the configuration matches the HttpConfig section above.
• For special modules that are for specific API endpoints, you should set “forceRelativeUrls” to only allow allow this configuration for requests to the specific origin / subpath.

<hibiki-config>
{
  "modules": {
      "app": {"type": "http",
              "baseUrl": "https://my.api.com/api/v2/",
              "forceRelativeUrls": true,
              "defaultHeaders": {
                  "X-UserId": {"hibikiexpr": "$.userid"},
                  "X-Domain-Id": "81288642"
              },
              "csrfToken": {"hibikiexpr": "$.apitoken"},
              "csrfParams": ["_token"]
      }
  }
}
</hibiki-config>

You can now use the ‘app’ module to make requests to “my.api.com” with the given HTTP settings:

# makes a GET request to https://my.api.com/api/v2/get-data
GET //@app/get-data(id=22);

# makes a POST request to https://my.api.com/api/v2/primary-name/set-name
POST //@app/primary-name/set-name(name='mike');