Halstack Client for JavaScript

Halstack Client for JavaScript enables developers to easily work with hypermedia-based APIs in a declarative manner. It offers a set of functionalities to facilitate the navigation between hypermedia resources and get access to their properties dynamically, based on the HAL and JSON Hyper-Schema draft specifications, as well as DXC API guidelines and HAL extensions.

This SDK is released as a client-agnostic library that can be used both in browser applications (such as Vanilla JS, React or Angular applications) or backend applications (NodeJS applications). As such, it is distributed as UMD.

Installation

npm install @dxc-technology/halstack-client

Use in Node.js

// require from the dependency the modules you need
const {
  HalResource,
  HalResponse,
  HalApiCaller,
} = require("@dxc-technology/halstack-client");

Use in browsers

// require from the dependency the modules you need
import {
  HalResource,
  HalResponse,
  HalApiCaller,
} from "@dxc-technology/halstack-client";

HalResource Factory

The purpose of this module is facilitating the access to the information of a given resource. This factory function receives a JSON object with the HAL Resource Representation as a parameter.

It returns a HalResource Object, encapsulating the original HAL Resource Representation and including a set of functions that will allow you to access the data from the resource in a declarative manner, without having to fully understand the details of how HAL resource representation is structured.

The HalResource can also be used to help developers to create a compliant HalResource representation to be included in a Hal response, exposing functions to add different sections that typically can be found in a resource.

HalResource Object

| Name | Type | Description | | :----------------------- | :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | resourceRepresentation | Object | The whole resource representation. | | getTitle | ()=>String | Returns the resource title. Taken from \_options.title. | | getInteractions | ()=>HalInteraction[] | Returns an array of HalInteraction objects. Taken from the \_options.links array. | | getInteraction | (String)=>HalInteraction | Receives a string with the rel of the interaction. Returns the HalInteraction object. | | getItems | ()=>Object[] | Returns an array of the original item link objects. Taken from the \_links.item array. | | getItem | (Number)=>Object | Receives the index of the item. Returns the item object. | | getLinks | ()=>Object[] | Returns an array of the original link objects (adding the rel), ignoring item link. Taken from the \_links object. | | getLink | (String)=>Object | Receives a string with the rel of the link. Returns the link object (adding the rel). | | getProperties | ()=>Object[] | Returns an array of HalProperty objects. Taken from the resource root level properties. | | getProperty | (String)=>Object | Receives a string with the key of the property. Returns the HalProperty object. | | getRequiredProperties | ()=>String[] | Returns an array with the required properties key. Taken from the \_options.required array. | | isPropertyRequired | (String)=>Bool | Receives the key of a property. Returns true if it exists within the \_options.required array. | | getSchemaProperties | ()=>Object[] | Returns an array of the original schema objects for properties (adding key). Taken from the \_options.properties object. | | getSchemaProperty | (String)=>Object | Receives the key of a property. Returns the property's schema object (adding key) if exists within \_options.properties object. | | addLink | (Object)=>void | Receives an object as parameter. This object can contain the usual link properties as { rel, name, href, title } where rel and href are required. The object will be added to the \links section using rel as key | | addLinks | (Object)=>void | Receives an object as parameter. This object can contain the usual link properties as { rel, name, href, title } where rel and href are required. The object will be added to the \links section using rel as key | | addTitle | (String)=>void | Assign the parameter received to the resource title in \_options.title | | addItem | (Object)=>void | Add the object received as parameter as a resource \_link item | | addItems | (Object[])=>void | Add every object in the list received as parameter as a resource \_link item. | | addProperties | (Object)=>void | Add the key:values found in the object received as parameter as resource properties. | | addOptionsProperties | (Object)=>void | Add every property received in parameter as property under the \_options.properties section | | addOptionsProperty | (Object)=>void | Add the property ({key: schema}) received in parameter as property under the \_options.properties section | | addInteraction | (Object)=>void | Add the object received as parameter ({rel: Interaction}) under the options.link section | | addOptions | (Object)=>void | It receives an object as parameter and add interactions , properties, required and title if those sections are found as object keys. |

HalInteraction Object

Includes the existing attributes of the original interaction object. It provides the following additional helper functions:

| Name | Type | Description | | :---------------------- | :----------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | | getRequiredProperties | ()=>String[] | Returns an array with the required properties key. Taken from the "schema.required" array of the interaction. | | isPropertyRequired | (String)=>Bool | Receives the key of a property. Returns true if it exists within the "schema.required" array of the interaction. | | getSchemaProperties | ()=>Object[] | Returns an array of the original schema objects for properties (adding key). Taken from the \schema.properties object of the interaction. | | getSchemaProperty | (String)=>Object | Receives the key of a property. Returns the property's schema object (adding key) if exists within \schema.properties object of the interaction. | | hasProperty | (String)=>Bool | Receives the key of a property. Returns true if it exists within the \schema.properties object of the interaction. |

HalProperty Object

| Name | Type | Description | | :-------------------- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------ | | isRequired | ()=>Bool | Returns true if the property exists within the \_options.required array. | | existsInInteraction | (String)=>Bool | Receives a string with the rel of an interaction. Returns true if the property exists within the "schema.properties" object of the interaction. | | getSchema | ()=>Object | Returns the property's schema object (adding key) if exists within \_options.properties object. |

HalResponse Factory

The purpose of this module is facilitating the access to the information returned inside an API response. This factory function accepts an object with the following attributes as a parameter:

| Name | Type | Description | | :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | | body | Object | The message-body is the data bytes transmitted associated with a http response. | | headers | Object | Contains the http headers which provide information about the server and about further access to the resource identified by the Request-URI. | | status | Number | Status codes are issued by a server in response to a client's request made to the server. It includes codes from IETF Request for Comments (RFCs). |

It returns HalResponse Object.

HalResponse Object

| Name | Type | Description | | :-------------------- | :------------ | :------------------------------------------------------------------------------------------------- | | body | JSON Object | Response message-body | | headers | JSON Object | Http headers | | status | Number | Https response code | | type | String | Response format. Example: application/JSON | | halResource | HalResource | HalResource Object composed using the information provided inside the body. | | containsHalResource | Bool | True if the content of the response is a HAL resource. |

HalApiCaller Module

This module is a HTTP client which takes care of handing out parsed HalResponses. It exports the following functions:

| Name | Type | Description | | :----------------- | :------------------------------ | :------------------------------------------------------------------------------------------------------------------------------ | | setGlobalHeaders | function | Receives a headers object that will be used for all http requests done with this module. | | get | function:Promise(HalResponse) | Receives a { url, headers } object as a parameter. Returns a promise and will pass a HalResponse object to the handler. | | options | function:Promise(HalResponse) | Receives a { url, headers } object as a parameter. Returns a promise and will pass a HalResponse object to the handler. | | patch | function:Promise(HalResponse) | Receives a { url, body, headers } object as a parameter. Returns a promise and will pass a HalResponse object to the handler. | | post | function:Promise(HalResponse) | Receives a { url, body, headers } object as a parameter. Returns a promise and will pass a HalResponse object to the handler. | | put | function:Promise(HalResponse) | Receives a { url, body, headers } object as a parameter. Returns a promise and will pass a HalResponse object to the handler. | | del | function:Promise(HalResponse) | Receives a { url, headers } object as a parameter. Returns a promise and will pass a HalResponse object to the handler. |

License

See Halstack Client License here

To Do

See our issues