ngx-api-utils

ngx-api-utils

ngx-api-utils is a lean library of utilities and helpers to quickly integrate any HTTP API (REST, Ajax, and any other) with Angular.

Inspired by:

• https://github.com/auth0/angular2-jwt
• https://angular.io/guide/http#intercepting-requests-and-responses.

Thanks to the respective developers, people and contributors of:

• Angular 6+
• @angular/cli and it's latest capabilities of creating and maintaining libraries
• local fork of fake-api-jwt-json-server from https://github.com/techiediaries/fake-api-jwt-json-server based on this wonderful article https://www.techiediaries.com/fake-api-jwt-json-server/ and utilizing this awesome https://github.com/typicode/json-server
• VS Code

Getting started

Installation

To install the package from npm - run npm install ngx-api-utils

Setup

import { NgxApiUtilsModule } from 'ngx-api-utils';

@NgModule({
  ...
  imports: [NgxApiUtilsModule,...]
  ...
})
export class AppModule { }

Usage

The package consists of couple of main services and a module that you would use:

• AuthTokenService to allow you to easily work with any kind of tokens, including but not limited to JWT, Oauth2 with JWT container, etc.
  • which you would provide with a proper TokenDecoder
  • you would also like to provide with proper TokenPayload by extending it with the properties you have in the token especially if you are using JWT Token or other that can contain relevant for your application information
  • you might want to provide it with your custom TokenStorage implementation especially if you are not happy with the default localStorage
• ApiHttpService that behaves 100% like Angular's HttpClient, but helps you by utilizing for you
  • the AuthTokenService internally and sending the token on each request using ApiAuthorizationHeaderInterceptor
  • also allows you to set API base url, by providing where the HTTP API is thanks to API_HTTP_BASE_URL
  • also allows you to set default HTTP headers with ApiDefaultHeadersInterceptor
  • also only in case needed you can plug ApiErrorsInterceptor and read through it the last error
  • or even better - have your own implementation of any interceptor you need - to handle errors, transform results or anything you would the same way you would do for Angular's HttpClient, just provide it like the defaults are provided with API_HTTP_INTERCEPTORS injection token e.g. {provide: API_HTTP_INTERCEPTORS, useClass: YourCoolInterceptor, multi: true} to line up with the rest of the default provided API_HTTP_INTERCEPTORS
• ApiAuthGuardService that is a perfectly sane option of you just have public and private part that needs to be protected based on AuthTokenService validity and you want a bit more
  • you can of course configure it with urls for API_AUTH_GUARD_URL_FOR_AUTHENTICATED and API_AUTH_GUARD_URL_FOR_AUTHENTICATION, also a RegExp for API_AUTH_GUARD_PUBLIC_ONLY_ROUTES
• NgxApiUtilsModule that provides a default set of interceptors for API_HTTP_INTERCEPTORS used by the ApiHttpService which you can configure through providing your own values for the relevant injection tokens

For more details, please check:

• the Demo app (TBD)
• the key ngx-api-utils specs

Demo

This repository contains a Demo app (TBD) that is intended to show a bit more complex app and how the ngx-api-utils package fits in.

In the demo beside the usage of ngx-api-utils I would strongly recommend checking:

• the overall structure of well organized lazy loaded modules https://github.com/ngx-api-utils/ngx-api-utils/tree/master/src/app though the router configurations
• the overall multi-layout system for the UI (HTML/CSS), that allows you to have different UI layouts for the different app sections (roles)
• the overall way how to organize your services around and build object models that utilize the ngx-api-utils (TBD)

Want to help?

The project uses the following things, you should get familiar with:

• @angular/cli's capabilities of creating and maintaining libraries
• local fork of this repository https://github.com/techiediaries/fake-api-jwt-json-server based on this wonderful article https://www.techiediaries.com/fake-api-jwt-json-server/ and utilizing this awesome https://github.com/typicode/json-server
• custom set of scripts that you can check https://github.com/ngx-api-utils/ngx-api-utils/blob/master/package.json#scripts that allows you to:
  • start the Demo app with npm run start
  • run the whole set of linters npm run start
  • run the e2e tests of the Demo app npm run e2e (TBD)
  • build the ngx-api-utils package itself through npm run ngx-api-utils:build
  • or run it's unit and integration tests through npm run ngx-api-utils:test
  • and more, please do check the scripts

Please feel free to submit PRs for the following things:

• test coverage - unit; integration tests; e2e tests on the demo app;
• demo project - showing the package in action in a bit more advanced architecture of modules and routing, namely public section, customer section, admin section of the app
• demo project fake api - needs updates according to what the demo would show
• contribute further - any additional features and bug fixes

We highly appreciate your contribution!