ng2-rest-api

Ng2-rest-api - is a rest api provider for angular 2 for http actions request to server and instantiate models.

• Describe api to define endpoints and actions
• Improves code-reusability by separating configuration from code that does actual work.
• That simplifies common GET, POST, DELETE, and UPDATE requests.
• Use a parameterized URLs.
• Easy headers read.
• Cache requests (todo)

If you need - you can get plain text response (It is sometimes convenient, but do not overdo it)

For Angular 1: https://github.com/zaqqaz/ng-rest-api

Installation

To install this library, run:

$ npm install ng2-rest-api --save

NEXT STEPS

1. Describe models
2. Create config
3. Add to @NgModule and execute static method configure.
4. Advice: use ApiProvider only in managers/services not from controllers.
5. Enjoy!

Config

You should describe endpoints and http Actions. Ng2-rest-api already had config for popular actions (get(GET),query(GET, array), update(PUT), patch(PATCH), remove(DELETE)). But if you need you can override them and add any others.

Let's look at the interfaces for config:

ApiConfig

interface ApiConfig {
  baseUrl: string,  // e.g. http://example.com:8080/api
  endpoints: Endpoint[]
}

Endpoint

interface Endpoint {
  name: OpaqueToken; // The name of emdpoint.
  route: string; // A parameterized part of URL
  model?: any; // {Object} - model on which will be mapped response, if no - return JSON object.
  actions?: Action[]; // Hash with declaration of custom actions that will be available in addition to the default set of default actions.
}

route - A parameterized part of URL template with parameters prefixed by : as in /user/:username. If you are using a url with a suffix, just add the suffix, like this: '/resource.json' or '/:id.json' or even '/resource/:resource_id.:format' If the parameter before the suffix is empty, :resource_id in this case, then the /. will be collapsed down to a single .. If you need this sequence to appear and not collapse then you can escape it with /\..

Action

interface Action {
   name: string, // The name of action.
   method: string, // Case insensitive HTTP method (e.g. GET, POST, PUT, DELETE, JSONP, etc).
   instantiateModel?: boolean, // need do instatiate model ? default - true; if no - return plain text response.
   isArray?: boolean, // If true then the returned object for this action is an array,
   headersForReading?: Array<string>, // Headers which need read
   params?: any, // Optional set of pre-bound parameters for this action
   cache?: any // todo
 }

params - Default values for url parameters. These can be overridden in actions methods. If a parameter value is a function, it will be called every time a param value needs to be obtained for a request (unless the param was overridden). The function will be passed the current data value as an argument. Each key value in the parameter object is first bound to url template if present and then any excess keys are appended to the url search query after the ?. Given a template /path/:verb and parameter {verb:'greet', salutation:'Hello'} results in URL /path/greet?salutation=Hello. If the parameter value is prefixed with @, then the value for that parameter will be extracted from the corresponding property on the data object (provided when calling a "non-GET" action method). For example, if the defaultParam object is {someParam: '@someProp'} then the value of someParam will be data.someProp. Note that the parameter will be ignored, when calling a "GET" action method (i.e. an action method that does not accept a request body)

How to use

// api: ApiProvider
// endpointName: {OpaqueToken} - endpoint name from config.
// actionName: {string} - default action name or any from config.
// body: {object} - body data for POST request. If is GET request body use as params
// params: {object} - additional params which will be mixed with pre-bound parameters for this action and override them if will has the same key.
this.api.endpoint(endpointName).action(actionName', body, params);

Examples:

Model

import {Image} from 'api/models/Image';

export class Post {
  id?: number;
  title: string;
  description: string;
  content: string;
  image: Image | any;

  constructor({id, title, description, content, image}:
              {id?: number, title: string, description: string, content: string, image: Image|any}) {
    this.id = id;
    this.title = title;
    this.description = description;
    this.content = content;
    this.image = new Image(image);
  }

  beforeSave() {
    if (this.image) {
      this.image = this.image.id;
    }
  }
}

Config:

import {OpaqueToken} from "@angular/core";
import {Post} from "api/models/Post";

// endpoints
export const POSTS = new OpaqueToken('POSTS');

// config
export const apiConfig = {
  baseUrl: 'http://localhost:3000',
  endpoints: [
    {
      name: POSTS,
      model: Post,
      route: '/posts/:id',
      actions: [
        {
          name: 'query',
          method: 'GET',
          isArray: true,
          headersForReading: ['X-Total-Count'],
          params: {limit: 10}
        }
      ]
    }
  ]
};

@NgModule

import {BrowserModule} from '@angular/platform-browser';
import {NgModule} from '@angular/core';
import {FormsModule} from '@angular/forms';
import {HttpModule} from '@angular/http';

import {AppComponent} from './app.component';
import {MainComponent} from './endpoints/main/main.component';
import {RouterModule} from '@angular/router';
import {routes} from './app.routes'
import {TypingCarouselDirective} from "./endpoints/main/typing-carousel.directive";
import {LoaderComponent} from './shared/loader/loader.component';
import {Ng2RestApiModule, ApiProvider} from "ng2-rest-api";
import {apiConfig} from "api/config";

import {PostsManager} from './api/services/PostsManager';
import { PostsComponent } from './endpoints/posts/posts.component';

@NgModule({
  declarations: [
    AppComponent,
    MainComponent,
    TypingCarouselDirective,
    LoaderComponent,
    PostsComponent
  ],
  imports: [
    BrowserModule,
    FormsModule,
    HttpModule,
    RouterModule.forRoot(routes),
    Ng2RestApiModule.configure(apiConfig)
  ],
  providers: [ApiProvider, PostsManager],
  bootstrap: [AppComponent]
})
export class AppModule {
}

Service

import {ApiProvider} from "ng2-rest-api";
import {POSTS} from "api/config";
import {Injectable} from "@angular/core";
import {Post} from "api/models/Post";

@Injectable()
export class PostsManager {
  constructor(private api: ApiProvider) {
  }

  getPost(id: number) {
    return this.api.endpoint(POSTS).action('get', {id});
  }

  queryPosts(query: string, offset: number) {
    return this.api.endpoint(POSTS).action('query', {query, offset});
  }

  savePost(post: Post) {
    return post.id ? this.api.endpoint(POSTS).action('update', post) : this.api.endpoint(POSTS).action('save', post);
  }
}

Controller

import {Component, OnInit} from '@angular/core';
import {PostsManager} from 'api/services/PostsManager';
import {Post} from 'api/models/Post';
import {Image} from 'api/models/Image';

@Component({
  selector: 'app-post',
  templateUrl: './post.component.html',
  styleUrls: ['./post.component.scss']
})
export class PostComponent implements OnInit {

  constructor(private postsManager: PostsManager) {}

  example() {
    // search 'evolution' posts with offset = 0
    this.postsManager.queryPosts('evolution', 0).subscribe(([posts, headers]) => {
      this.total = headers['X-Total-Count'];
      this.posts = posts;
      console.log('Response', this.posts, 'X-Total-Count', this.total);
    });

    // get post with id 1
    this.postsManager.getPost(1).subscribe(post => {
      console.log('SINGLE', post);

      // update post
      post.content = 'updated content';
      this.postsManager.savePost(post).subscribe(p => console.log('updated'));
    });

    // create new post
    this.postsManager.savePost(new Post({
      title: 'test',
      description: "test",
      content: 'test',
      image: new Image({id: 1, src: ''})
    })).subscribe(p => console.log('saved'));
  }
}

To Do

• Improve documentation.
• Cache
• Add tests
• Method to set headers for all actions, and for specific. (Authorization token etc.)

Cache

Will be implemented soon.