@flowup/ng2-api

Ng2Api

Ng2-api is a package that allows to consume Http JSON APIs while retaining type-safety.

Table of contents

• Installation
• Basic implementation examples
• Build
• Running unit tests
• Contribution

Installation

You can install ng2-api via

• yarn

$ yarn add @flowup/ng2-api

• npm

$ npm install @flowup/ng2-api --save

Basic implementation example

:robot: Please follow the Basic usage for the full example.

Ng2API supports GET, POST, PUT and DELETE calls in it's base. All methods can be called on a single model or array, e.g.: get(modelArray) or getSingle(model).

1) Initialize the module:

import { NgModule } from '@angular/core';
import { Ng2APIModule } from '@flowup/ng2-api';

@NgModule({
  imports: [
    Ng2APIModule.forRoot('base_serve_url.com', [
      'BookResource', 'UserResource' // resources to be initialized
    ])
  ]
})
class AppModule {
}

2) Define a model and a service afterwards

import { APIConfig, Resource } from '@flowup/ng2-api';
import { Injectable, Inject } from '@angular/core';
import { Observable } from 'rxjs';

const USER_API_ENDPOINT = '/users';

// api endpoint model
export interface User {
  email: string,
  id?: number
}

@Injectable()
export class UserService {
  // inject desired resources to the user service,
  //  the name of resource specified in @Inject is one of specified in module
  constructor(@Inject('UserResource') private users: Resource<User>) {
    this.users.setResourceBase(USER_API_ENDPOINT);
  }

  getUserById(id: number): Observable<User> {
    // args will be added into the url: /users/:id
    return this.users.getSingle({args: [id]});
  }

  createUser(user: User): Observable<User> {
    // pass the user object as model
    return this.users.create(user);
  }
}

3) Use the service within a component

@Component({...})
class MyComponent {
  constructor(private users: UserService) {
  }

  createUser(user: User) {
    let user = this.users.createUser(user);
  }

  getUserById(id: number) {
    let user = this.users.getUserById(id);
  }
}

**Use Resource in ngrx/effect **

const BOOK_API_ENDPOINT = '/books'

@Injectable()
export class BooksEffect {
  constructor(private actions: Actions, @Inject('BookResource') private books: Resource<Book>) {
    this.books.setResourceBase(BOOK_API_ENDPOINT);
  }

  @Effect() getNotifications: Observable<Action> = this.actions
    .ofType('GET_BOOKS')
    .switchMap(() => this.books.get()
      .map(response =>({type: 'GET_BOOKS_SUCCESSFUL', payload: response}))
      .catch(err => Observable.of({type: 'GET_BOOKS_FAILURE', payload: err})));
}

Another way of usage is extend Resource class

class BookService extends Resource<Book> {
  // inject and pass config, http and relative path to the Resource
  constructor(config: APIConfig, http: Http) {
    // initialize Resource
    super(config, http, '/users');
  }
}

For more examples visit the Cookbook

• Basic usage
• JWT Authorization
• Extending headers

Build

Run yarn build to build the project. The build artifacts will be stored in the dist/ directory.

Running unit tests

Run yarn test to execute unit and e2e tests.

Contributing

If you would like to contribute, read first through Angular contribution guidelines. Get the repository

$ git clone https://github.com/flowup/ng2-api.git