npm package: @frontendart/smdb-api
Description: SMDB API service components
Latest version: 0.1.1

# SmdbApi

This library contains various services that help connecting to and getting data from SMDB system.
It can be used as a stand-alone dependency or together with the **smdb-widgets** library.

## Using the library

If you want to use the library in your project, you have to import the `SmdbApiModule` through its `.forRoot()` method like below:

```javascript
import {SmdbApiModule} from '@frontendart/smdb-api';

@NgModule({
  declarations: [AppComponent],
  imports:      [   
    SmdbApiModule.forRoot(),
  ],
  providers:    [],
  bootstrap:    [SmdbAppComponent]
})
export class AppModule {
}
```

After importing the `SmdbApiModule`, you will be able to inject the `SmdbApiService` service as usual:

```javascript
@Component()
export class SampleComponent {

  constructor(private smdbApi: SmdbApiService) { }
```

Then, you will be able to use the various service calls that the API provides.

### Caching

To reduce traffic, the lib can be configured to use an internal HTTP request caching mechanism that stores responses for a given URL for a short (or not-so-short) time.
This is turned on by default, but can be turned off (and configured further - see below) when importing the `SmdbApiModule`.

The implementation is an HttpInterceptor that listens for every HTTP request and checks the URL if it has been previously visited. 
Request-response data is stored in a simple Map data structure.

### Configuration

There are some options you can configure the library:

|Option|Type|Explanation|Default value|
|------|----|-----------|-------------|
|cache.enabled|boolean|Turn caching on/off|true|
|cache.url|string &#124; string[]|URL pattern(s) which the caching should be made on. It must be a valid RegEx expression (e.g. new RegEx(url)), and it can be a single string or an array|api|
|cache.expiration|number|Expiry time _in seconds_|60|
|baseUrl|string|URL of the SMDB API|http://smdb-prod.frontendart.com/api|
    
If you use the `SmdbApiModule.forRoot()` syntax like above, you will have the library configured with the default values in the table.
If you want to customize some (or all) options, you should import the module like this:

```javascript
SmdbApiModule.forRoot({
                          cache:   {
                              enabled:    true,
                              expiration: 60000,
                              url:        'api'
                            },
                            baseUrl: 'http://smdb-prod.frontendart.com/api'
                          }),
```  

## Development

Currently, there is a single service file called `smdb-api-service.ts`. Every possible API calls should be placed here.
The general form of calling an API method through the service is by calling the `sendGet()` or `sendPost()` methods of the class.
The signature of these methods are very similar: they take a number of parameters and return an Observable that the caller can subscribe to.
Possible parameters are:
* url: string - the path of the API (without the base URL)
* params|body: any - query parameters (GET) or request body (POST/PUT)
* tokenDetails: TokenDetails - the user's API token
* transform: function - a transform function to process the API response. Defaults to return the `data` property  

The exact format is:
```javascript
(url: string, 
 params?: any, 
 tokenDetails?: TokenDetails, 
 transform: (data) => any = (data) => data.data): Observable<any>
```

## Build

Run `ng build smdb-api` to build the project. Be sure you are in the project main directory. 
The build artifacts will be stored in the `dist/` directory.

## Running unit tests

Run `ng test smdb-api` to execute the unit tests via [Karma](https://karma-runner.github.io).