api.service.HttpClient

This service component provides a convenient client for sending requests to remote services via HTTP or HTTPS.

Consider LocalClientRequest for local requests

This service is a wrapper for an HTTP client suitable for sending requests to remote services as well as to the local Hitchy runtime as it is listening to HTTP request as well.

However, there is another service for sending request to the local instance of Hitchy that works without the overhead of handling network communications in general and HTTP in particular.

Usage Example

The following excerpt is demonstrating how to use the HttpClient in another component.

export default function() {
    const api = this;
    const { service } = api;

    class YourComponent {
        static async checkSomeSite() {
            const res = await service.HttpClient.fetch( 
				"GET", "https://foo.example.com/api/endpoint", null, {
                    "x-api-key": "someaccesstoken",
                } );

			const data = await res.json();

            // TODO inspect data which is an object
        }
    }

    return YourComponent;
}

Fetching Resource

Static method HttpClient.fetch() is starting new request for fetching resource from provided URL. Its signature is:

HttpClient.fetch( method, url, body, headers, options ).then( response => {} );

• method is selecting HTTP method to use for request.

• url is a string or instance of URL describing URL of resource to be fetched.

• body provides a request body. It may be:

  • null for requests that do not have a request body,
  • a Buffer sent as-is,
  • a string sent as-is,
  • a readable stream to be consumed for delivering the actual request body or
  • an object to be serialized in JSON format.

• headers is a regular object providing a set of custom request headers.

• options is optionally customizing the request handling. It currently supports these options:

  • A rough timeout may be given in seconds. It's primarily used to limit time request or response handling is waiting for either phase to complete.

Processing Response

Method HttpClient.fetch() is returning promise which is fulfilled with a response unless encountering severe issues on sending request.

The response is an IncomingMessage basically providing a statusCode property containing HTTP status code as returned by fetched resource as well as all response headers in property headers.

In addition there are two helper methods provided for simplifying access on response body:

• response.body() is promising the response body as raw Buffer.
• response.json() is promising the data found in response body parsed as JSON.

You can use both functions simultaneously. Either function is consuming the (remaining) response body, thus you can not consume it yourself afterward.