@o3r/apis-manager NPM

This package is an Otter Framework Module.

Description

This module provides services to help you communicate with your APIs. Its responsibility is to provide an API configuration to a service factory so that it could instantiate an API with the right configurations.

It contains a default configuration and a map of specific configurations for API / set of API. Configurations are only exposed through the method getConfiguration, which will merge the default configuration and the requested one.

How to install

ng add @o3r/apis-manager

Warning: this module requires @o3r/core to be installed.

Usage

The API Manager Module will need to be imported and configured in the application module which will then be used by the ApiFactory.

Application side configuration

The ApiManager requires the default Api Client which will be used in all the APIs and support a second parameter that allows the user to define specific Api Client per APIs.

export const apiManager = new ApiManager(
  new ApiFetchClient({
    basePath: PROXY_SERVER,
    requestPlugins: [new ApiKeyRequest('YourApiKey', 'Authorization')]
  }),

  {
    ExampleApi: // <--custom config for ExampleApi, using jsonToken plugins. If fields are not provided, the default ones will be taken.
      new ApiFetchClient({
      requestPlugins: [new JsonTokenRequest()],
      replyPlugins: [new ReviverReply(), new ExceptionReply(), new JsonTokenReply()]
    })
  }
);

@NgModule({
  imports: [
    ...,
    ApiManagerModule.forRoot(apiManager);
  ]
})

The ApiManager instance can be customized via factory provided to API_TOKEN:

export function apiFactory(eventTrackService: EventTrackService): ApiManager {

  const apiConfig: ApiClient = new ApiFetchClient(
    {
      basePath: PROXY_SERVER,
      requestPlugins: [new ApiKeyRequest('YourApiKey', 'Authorization')],
      fetchPlugins: [new PerformanceMetricPlugin({
        onMarkComplete: (m: Mark) => eventTrackService.addSDKServerCallMark(m)
      })]
    }
  );

  return new ApiManager(apiConfig, {
    LoggingApi: new ApiFetchClient({basePath: '/api'})
  });
}

@NgModule({
  imports: [
    ...,
    ApiManagerModule
  ],
  providers: [
    ...,
    {provide: API_TOKEN, useFactory: apiFactory, deps: [EventTrackService]}
  ]
})

Retrieve API instance with configuration

The API instances can be retrieved via the injection of the ApiFactory provided by the ApiManagerModule.

import { ExampleApi } from '@shared/sdk';

@Inject()
class MyClass {

  constructor(private apiFactoryService: ApiFactoryService) {
  }

  doSomething() {
    const exampleApi = apiFactoryService.getApi(ExampleApi); // <- retrieve example API instantiated with set configuration
    const call = exampleApi.doSomething({ ... });
  }

}

Warning : Do not forget to import the ApiManagerModule in you component module

Enforce custom API usage

Some users may want to enforce existing components or services to use a specific Sdk instead of default API SDK. To do so the INITIAL_APIS_TOKEN will allow to indicate to the ApiFactory the class they will need to use (instead of default ones).

In the AppModule:

import { ExampleApi, AnotherExampleApi } from '@custom/sdk';
import { INITIAL_APIS_TOKEN } from '@o3r/apis-manager';

@NgModule({
  providers: {
    { provide: INITIAL_APIS_TOKEN, useValue: [ExampleApi, AnotherExampleApi] }
  }
})
class AppModule {};

Then the following code (from an existing component) will use the custom Api:

import { ExampleApi } from '@shared/sdk';
import { ApiFactoryService } from '@o3r/apis-manager';

@Injectable()
class MyClass {

  constructor(private apiFactoryService: ApiFactoryService) {
  }

  doSomething() {
    const exampleApi = apiFactoryService.getApi(ExampleApi); // <- retrieve example API instantiated from the @custom/sdk
    const call = exampleApi.doSomething({ ... });
  }

}

Note : Even though the components that you reuse from a library are importing @shared/sdk, the ApiFactoryService will provide at runtime the one that you provided in your app module

Override configuration after instantiation

The configuration can be overridden after the instantiation of the API.

import { ExampleApi } from '@shared/sdk';
import { ApiFactoryService, INTERNAL_API_TOKEN } from '@o3r/apis-manager';

@Injectable()
class MyClass {

  constructor(@Inject(INTERNAL_API_TOKEN) private apiManager: ApiManager, private apiFactoryService: ApiFactoryService) {
  }

  doSomething() {
    this.apiManager.setConfiguration(new ApiFetchClient(), ExampleApi); // <- override configuration for Example API
    const exampleApi = apiFactoryService.getApi(ExampleApi, true); // <- retrieve example API with the new configuration (and update the cache)
  }

}

Helper functions

Preconnect

The appendPreconnect function adds a preconnect element to the DOM. This can be used to inform the browser that resources from a certain origin will be needed in the future, so that the browser can start resolving DNS, establishing TCP connections, and performing TLS handshakes early, reducing the overall page load time.

To use this function, simply call it with the baseUrl parameter set to the origin of the resource you will need in the future. If you want to add the crossorigin attribute to the link element, set the supportCrossOrigin parameter to true. For example:

import { appendPreconnect } from '@o3r/apis-manager';

appendPreconnect('https://your-api.com', true);

This will add a preconnect link element to the DOM with the href attribute set to https://example.com and the crossorigin attribute set to an empty string.