2017.04.01 Under Construction

The Hrequest package leverages the ARCcore.filter library to to provide data validation and normalization of HTTP request and response data messages in derived application-layer code.

Hrequest package exports two filter factory functions that allow developers to construct Node.js and browser client-specific variants of Hrequest filters.

The back-end Hrequest variant wraps the popular request library package.

And, the front-end Hrequest variant wraps the browser's XMLHttpRequest API.

Construction

Constructing an Hrequest instance builds three ARCcore.filter objects:

• The main Hrequest filter that your application calls to initiate an asynchronous HTTP request.
• A result filter that wraps your asynchronous result handler callback function.
• An error filter that wraps your asynchronous error callback function handler.

Implementation

The library implementation validates and normalizes your request data using a filter specification and then delegates to either request or XMLHttpRequest depending on execution context.

When the HTTP request completes, Hrequest examines the response and delegates to either the result or error filters that wrap the result and error callback functions you provide at construction.

Not all successful HTTP requests return correct or expected information. For example, even small changes to the implementation of the remote HTTP server may invalidate some assumption that your application code relies on for correct operation.

So, if Hrequest has trouble validating and normalizing a successful HTTP response it is considered an application-level error and the error filter is called instead of the result filter.

Use Cases

Hrequest was designed primarily for use with the Holism application server that uses similar patterns based on the ARCcore.filter library to enforce API message contracts.

But there's no reason that you cannot use Hrequest outside of this context as well.

The main use cases for Hrequest are product stability, security, and developer experience.

Hrequest catches and reports bugs and subtle problems (e.g. mismatched client / server versions) quickly allowing developers to diagnose and correct the issue(s) in their development environment. And, this is always significantly less time consuming and stressful than dealing with a broken production deployment.

The last and perhaps most interesting use case for Hrequest involves publishing or making available via API's the filter specification documents used to enforce critical internal messaging and external-facing API contracts.