Generic http client for the IMA application framework.
npm install @ima/plugin-http-clientGeneric http client for the IMA application framework.
``console`
npm install @ima/plugin-http-client --save
You can add HttpClient alias.
`js
//bind.js
import { HttpClient } from '@ima/plugin-http-client';
oc.bind('$HttpClient', HttpClient);
//optionally you can add default processors to httpClient
oc.constant('HttpClientDefaultProcessors', [AdditionalPostProcessor, SuperProcessor]);
`
You can register some processors.
`js
//services.js
import { EntityProcessor } from '@ima/plugin-http-client/rest';
const httpClient = oc.get('$HttpClient');
httpClient.registerProcessor(oc.get(EntityProcessor));
`
Then you can use HttpClient
`js
class ExampleHttpCall {
#httpClient: HttpClient;
static get $dependencies(): Dependencies {
return [HttpClient];
}
constructor(httpClient: HttpClient) {
this.#httpClient = httpClient;
}
async callAPI() {
const url = 'https://example.com/api/author';
const {response} = await this.#httpClient.request(
{
method: 'get',
url
}
);
return response;
}
}
`
Examples of request options:
`js`
{
[OPTION_TRANSFORM_PROCESSORS]: processors => ([...processors, newProcessor])
}
{
[OPTION_TRANSFORM_PROCESSORS]: processors => processors.filter(item=>!(item instanceof NewProcessor))
}
Example:
`js`
export class EntityProcessor extends AbstractProcessor {
postRequest(params: ProcessorParams) {
const { response, additionalParams } = params;
if (response) {
const { body } = response;
const entityClass = additionalParams?.resource?.entityClass;
if (body && entityClass) {
let newBody: object | object[];
if (body instanceof Array) {
newBody = body.map(entityData =>
Reflect.construct(entityClass, [entityData])
);
} else {
newBody = Reflect.construct(entityClass, [body]);
}
params.response = Object.assign({}, response, { body: newBody });
}
}
return params;
}
}
The result of each processor is patched in HttpClient, so it is sufficient to return the modified value as a result of the processor's action.
If the preRequest action returns a response object, the HttpAgent is no longer called, but comes straight to the postRequest action.
You have to set setting baseApiUrl for REST resources:
`js
//settings.js
...
plugin: {
httpClient: {
rest: {
baseApiUrl: 'YOUR BASE API URL'
}
}
},
...
`
#### Paths
You have to specify getter path to determine API path.
There are some build-in PathType like CREATE, GET, UPDATE, REPLACE, DELETE, but you can specify your own.
You can use in brackets some variables in paths.
Example:
`js/authors
class AuthorResource extends AbstractResource {
static get PathType() {
return {
...super.PathType,
LIST: 'list'
};
}
get path() {
return {
[this.constructor.PathType.LIST]: ,/authors/{$id}
[this.constructor.PathType.GET]:
};
}
list(data, options, pathType = this.constructor.PathType.LIST)
{
return super.get(data, options, pathType);
}
//optionally you can specify entityClass and use it with EntityProcessor
get entityClass() {
return AuthorEntity;
}
}
that can be directly used or extended.
The entity takes care of deserializing the data coming into the constructor
and also provides method for serialization.#### Data field mapping
BaseEntity defines
dataFieldMapping getter, which is used to deserialize/serialize the data.
You can use predefined mappers or create new ones to deserialize single value from an API to an entity value
and to serialize property from an entity to a plain value. You can also use string value to rename key.Example:
`js
...
get dataFieldMapping() {
return {
_id: 'id', // rename API value _id to id (_id doesn't exist in new entity)
metaKeywords: new DefaultToArray(), //if metaKeywords is not defined then the entity will contain an empty array for this field.
layout: new EntityMapper(BaseEntity), //transform layout object to BaseEntity
listOfAuthors: { mapper: new EntityListMapper(BaseEntity), newKey: 'authors' } //rename to authors and tranform to array of BaseEntities
};
}
...
`
$3
There are some predefined mappers:
* DefaultToArray - for given property defines empty array as default value
* EntityMapper - transforms value of property to given entity (given entity has to be instance of BaseEntity)
* EntityListMapper - transforms array of objects to array of given entitiesYou can also create new one:
Example:
js
class DateMapper extends BaseMapper {
deserialize(serializedDate) {
if (!serializedDate) {
return serializedDate;
}
const dateAndTime = serializedDate.split(' ');
const dateParts = dateAndTime[0].split('-');
const timeParts = dateAndTime[1].split(':');
return new Date(
dateParts[0],
dateParts[1] - 1,
dateParts[2],
timeParts[0],
timeParts[1],
timeParts[2],
0
);
} serialize(date) {
if (!date) {
return date;
}
const hours = formatNumber(date.getHours());
const minutes = formatNumber(date.getMinutes());
const seconds = formatNumber(date.getSeconds());
return
${date.getFullYear()}-${formatNumber(date.getMonth() + 1)}-${formatNumber(;
function formatNumber(number, digits = 2) {
let string = ${number};
while (string.length < digits) {
string = 0${string};
}
return string;
}
}
}
`$3
The
transforms the response from the API into entities in case there is entityClass` getter filled in Resource.