Angular 2 JSON API

A lightweight Angular 2 adapter for JSON API

Installation
Usage
TODO
Development
License

Installation

To install this library, run:

$ npm install angular2-jsonapi --save

If you use Angular-CLI, add the package to system-config.ts:

const map: any = {
  'angular2-jsonapi': 'vendor/angular2-jsonapi/dist'
};

const packages: any = {
  'angular2-jsonapi': {defaultExtension: 'js', main: 'index.js'}
};

and to angular-cli-build.js:

vendorNpmFiles: [
    // ...
    'angular2-jsonapi/dist/**/*.+(ts|js|js.map)'
]

Add the library's PROVIDERS to your bootstrap dependences:

import { PROVIDERS } from 'angular2-jsonapi';

bootstrap(AppComponent, [
  PROVIDERS
]);

Usage

Configuration

Firstly, create your Datastore service:

Extend the JsonApiDatastore class
Decorate it with @JsonApiDatastoreConfig, set the baseUrl for your APIs and map your models

import { JsonApiDatastoreConfig, JsonApiDatastore } from 'angular2-jsonapi';

@Injectable()
@JsonApiDatastoreConfig({
  baseUrl: 'http://localhost:8000/v1/',
  models: {
    posts: Post,
    comments: Comment
  }
})
export class Datastore extends JsonApiDatastore { }

Then set up your models:

Extend the JsonApiModel class
Decorate it with @JsonApiModelConfig, passing the type
Decorate the relationships attributes with @HasMany

import { JsonApiModelConfig, JsonApiModel, HasMany } from 'angular2-jsonapi';

@JsonApiModelConfig({
    type: 'posts'
})
export class Post extends JsonApiModel {

    title: string;
    content: string;

    @HasMany()
    comments: Comment[];
}

@JsonApiModelConfig({
    type: 'comments'
})
export class Comment extends JsonApiModel {

    title: string;

    post: Post;
}

Finding Records

Querying for Multiple Records

Now, you can use your Datastore in order to query your API with the query() method:

The first argument is the type of object you want to query.
The second argument is the list of params: write them in JSON format and they will be serialized.
When you want to get also the relationships, pass the include param with the type of object to be included as relationship.

// ...
constructor(private datastore: Datastore) { }

getPosts(){
    this.datastore.query(Post, {
        page: { size: 10, number: 1},
        include: Comment
    }).subscribe(
        (posts: Post[]) => console.log(posts)
    );
}

You will get an array of objects where every mapped relationship will be automatically resolved:

[
    Post{
        id: 1,
        title: 'My post',
        content: 'My content',
        comments: [
            Comment{
                id: 1,
                // ...
            },
            Comment{
                id: 2,
                // ...
            }
        ]
    },
    // ...
]

Retrieving a Single Record

Use findRecord() to retrieve a record by its type and ID:

this.datastore.findRecord(Post, 1).subscribe(
    (post: Post) => console.log(post)
);

You can also pass the options:

this.datastore.findRecord(Post, 1, {
    include: Comment
}).subscribe(
    (post: Post) => console.log(post)
);

Creating Records

You can create records by calling the createRecord() method on the datastore:

The first argument is the type of object you want to create.
The second is a JSON with the object attributes.

this.datastore.createRecord(Post, {
    title: 'My post',
    content: 'My content'
}).subscribe(
    (post: Post) => console.log(post)
);

If the object you want to create has a one-to-many relationship, you can do this:

this.datastore.createRecord(Comment, {
    title: 'My comment',
    post: Post
}).subscribe(
    (comment: Comment) => console.log(comment)
);

TODO

Implement everything from the JSON API specific.
Add unit testing and E2E testing

Development

To generate all *.js, *.js.map and *.d.ts files:

$ npm run tsc

To lint all *.ts files:

$ npm run lint

Thanks

This library is inspired by the draft of this never implemented library.

caiges/angular2-jsonapi