This is a JSON API library for Angular 4+. Please use ts-angular-jsonapi for AngularJS.
You can test library on this online example 👌 http://ngx-jsonapi.reyesoft.com/.
Data is obtained from Json Api Playground.
- Cache (on memory): Before a HTTP request objects are setted with cached data.
- Cache (on memory): TTL for collections and resources
- Cache on localstorage
- Pagination
- Filtering by attributes through a string or a regular expression
- Include param support (also, when you save)
- Two+ equal resource request, only one HTTP call.
- Equal requests, return a same ResourceObject on memory
- Default values for a new resource (hydrator).
- Properties on collections like
$length
,$is_loading
or$source
(empty
|cache
|server
)
More information on examples section.
First of all, you need read, read and read Jsonapi specification.
yarn install ngx-jsonapi --save
# or npm if you wish...
- Add Jsonapi dependency.
- Configure your url and other paramemeters.
- Inject JsonapiCore somewhere before you extend any class from
Jsonapi.Resource
.
import { NgModule } from '@angular/core';
import { NgxJsonapiModule } from 'ngx-jsonapi';
@NgModule({
imports: [
NgxJsonapiModule.forRoot({
url: '//jsonapiplayground.reyesoft.com/v2/'
})
]
})
export class AppModule { }
Like you know, the better way is with examples. Lets go! 🚀
authors.service.ts
import { Injectable } from '@angular/core';
import { Service, ISchema } from 'ngx-jsonapi';
@Injectable()
export class AuthorsService extends Service<Author> {
public resource = Author;
public type = 'authors';
public schema: ISchema = {
relationships: {
books: {
hasMany: true
},
photos: {
hasMany: true
}
}
};
}
export class Author extends Resource {
public attributes: {
name: string,
date_of_birth: string,
date_of_death: string,
created_at: string,
updated_at: string
};
}
import { Component } from '@angular/core';
import { ICollection } from 'ngx-jsonapi';
import { Author, AuthorsService } from './authors.service';
@Component({
selector: 'demo-authors',
templateUrl: './authors.component.html'
})
export class AuthorsComponent {
public authors: ICollection<Author>;
public constructor(
private authorsService: AuthorsService
) {
authorsService.all(
// { include: ['books', 'photos'] }
)
.subscribe(
authors => {
this.authors = authors;
console.info('success authors controller', authors);
},
error => console.error('Could not load authors.')
);
}
}
<p *ngFor="let author of authors.$toArray">
id: {{ author.id }} <br />
name: {{ author.attributes.name }} <br />
birth date: {{ author.attributes.date_of_birth | date }}
</p>
Filter resources with attribute: value
values. Filters are used as 'exact match' (only resources with attribute value same as value are returned). value
can also be an array, then only objects with same attribute
value as one of values
array elements are returned.
let authors = authorsService.all(
{
localfilter: { name: 'xx' }, // request all data and next filter locally
remotefilter: { country: 'Argentina' } // request data with filter url parameter
}
);
From this point, you only see important code for this library. For a full example, clone and see demo directory.
let author = authorsService.get('some_author_id');
let author$ = authorsService.get(
'some_author_id',
{ include: ['books', 'photos'] }
);
TIP: these parameters work with all()
and save()
methods too.
let author = this.authorsService.new();
author.attributes.name = 'Pablo Reyes';
author.attributes.date_of_birth = '2030-12-10';
author.save();
let author = this.authorsService.new();
author.attributes.name = 'Pablo Reyes';
author.attributes.date_of_birth = '2030-12-10';
// some_book is an another resource like author
let some_book = booksService.get(1);
author.addRelationship(some_book);
// some_publisher is a polymorphic resource named company on this case
let some_publisher = publishersService.get(1);
author.addRelationship(some_publisher, 'company');
// wow, now we need detach a relationship
author.removeRelationship('books', 'book_id');
// this library can send include information to server, for atomicity
author.save( { include: ['book'] });
// mmmm, if I need get related resources? For example, books related with author 1
let relatedbooks = booksService.all( { beforepath: 'authors/1' } );
// you need get a cached object? you can force ttl on get
let author$ = authorsService.get(
'some_author_id',
{ ttl: 60 } // ttl on seconds (default: 0)
);
authorsService.get('some_author_id')
.suscribe(
author => {
this.author.attributes.name += 'New Name';
this.author.save(success => {
console.log('author saved!');
});
}
)
let authors$ = authorsService.all(
{
// get page 2 of authors collection, with a limit per page of 50
page: { number: 2 ; size: 50 }
}
);
- number: number of the current page
- size: size of resources per page (it's sended to server by url)
- information returned from server (check if is avaible) total_resources: total of avaible resources on server resources_per_page: total of resources returned per page requested
You can run JsonApi Demo App locally following the next steps:
git clone git@github.com:reyesoft/ngx-jsonapi.git
cd ngx-jsonapi
yarn
yarn start
We use as backend Json Api Playground.
Check Environment development file 😉.