Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/reyesoft/ngx-jsonapi
JSON API client library for Angular 5+ 👌 :: Production Ready 🚀
https://github.com/reyesoft/ngx-jsonapi
angular angular2 angular4 jsonapi jsonapi-library jsonapiclient
Last synced: 4 days ago
JSON representation
JSON API client library for Angular 5+ 👌 :: Production Ready 🚀
- Host: GitHub
- URL: https://github.com/reyesoft/ngx-jsonapi
- Owner: reyesoft
- License: mit
- Created: 2017-10-08T00:59:37.000Z (over 7 years ago)
- Default Branch: v3.0
- Last Pushed: 2024-06-06T19:00:19.000Z (7 months ago)
- Last Synced: 2024-12-29T11:11:27.086Z (11 days ago)
- Topics: angular, angular2, angular4, jsonapi, jsonapi-library, jsonapiclient
- Language: TypeScript
- Homepage: https://ngx-jsonapi.reyesoft.com/
- Size: 7.89 MB
- Stars: 101
- Watchers: 10
- Forks: 52
- Open Issues: 62
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# ngx-jsonapi
[](https://github.com/reyesoft/ngx-jsonapi)
[](https://circleci.com/gh/reyesoft/ngx-jsonapi) [](https://www.codacy.com/app/Swimlane/ngx-charts?utm_source=github.com&utm_medium=referral&utm_content=swimlane/ngx-charts&utm_campaign=Badge_Grade) [](https://badge.fury.io/js/ngx-jsonapi) [](https://coveralls.io/github/reyesoft/ngx-jsonapi?branch=master)
This is a JSON API library for Angular 6+. Please use [ts-angular-jsonapi](https://github.com/reyesoft/ts-angular-jsonapi) for AngularJS.
## Online demo
You can test library on this online example 👌 .
[](http://ngx-jsonapi.reyesoft.com/)
Data is obtained from [Json Api Playground](https://jsonapiplayground.reyesoft.com/) server.
## Supported features
- Cache (on memory): TTL for collections and resources. Before a HTTP request objects are setted with cached data.
- Cache on IndexedDB
- Pagination
- Sorting
- [Include param support](http://jsonapi.org/format/#fetching-includes) (also, when you save)
- Equal requests, return a same ResourceObject on memory
- Default values for a new resource (hydrator).
## Migration
- [Migration v1 to v2 update guide](https://github.com/reyesoft/ngx-jsonapi/blob/v2.0/docs/migration.md)
- [Migration v2 to v3 Angular update guide](https://github.com/reyesoft/ngx-jsonapi/blob/v2.0/docs/migration-v2-to-v3.md)
## Usage
Just [install](#installation), [configure](#dependecies-and-customization) and learn with [examples](#examples).
First of all, it's advisable to read [Jsonapi specification](http://jsonapi.org/). Understanding JsonApi documents structure is recommended.
### Installation
```bash
yarn add [email protected] --save
# or npm if you wish...
```
### Dependecies and customization
1. Add Jsonapi dependency.
2. Configure your url and other paramemeters.
- Angular
```typescript
/* .. */
import { NgxJsonapiModule } from 'ngx-jsonapi';
@NgModule()
export class AppModule {
public constructor() {
JsonapiBootstrap.bootstrap({
user_config: { url: '//jsonapiplayground.reyesoft.com/v2/' }
});
}
}
```
- React
```typescript
import { NgxJsonapiModule } from 'ngx-jsonapi';
const App = () => {
JsonapiBootstrap.bootstrap({
user_config: { url: '//jsonapiplayground.reyesoft.com/v2/' }
});
return
Hello world;
};
```
### Enable Local Cache
Library cache anything memory. With Local Store, also store all on IndexDb on browser. Faster apps when we reuse a lot of data.
- Angular
```typescript
/* .. */
import { NgxJsonapiModule, StoreService, JsonRipper } from 'ngx-jsonapi';
@NgModule()
export class AppModule {
public constructor() {
JsonapiBootstrap.bootstrap({
user_config: { url: '//jsonapiplayground.reyesoft.com/v2/' },
jsonapiStore: new StoreService(),
jsonRipper: new JsonRipper()
});
}
}
```
- React
```typescript
import { NgxJsonapiModule } from 'ngx-jsonapi';
const App = () => {
JsonapiBootstrap.bootstrap({
user_config: { url: '//jsonapiplayground.reyesoft.com/v2/' },
jsonapiStore: new StoreService(),
jsonRipper: new JsonRipper()
});
return
Hello world;
};
```
## Examples
Like you know, the better way is with examples. Lets go! 🚀
### Defining a resource
`authors.service.ts`
```typescript
import { Injectable } from '@angular/core';
import { Autoregister, Service, Resource, DocumentCollection, DocumentResource } from 'ngx-jsonapi';
import { Book } from '../books/books.service';
import { Photo } from '../photos/photos.service';
export class Author extends Resource {
public attributes = {
name: 'default name',
date_of_birth: ''
};
public relationships = {
books: new DocumentCollection(),
photo: new DocumentResource()
};
}
@Injectable()
@Autoregister()
export class AuthorsService extends Service {
public resource = Author;
public type = 'authors';
}
```
### Get a collection of resources
#### Controller
```typescript
import { Component } from '@angular/core';
import { DocumentCollection } from 'ngx-jsonapi';
import { AuthorsService, Author } from './../authors.service';
@Component({
selector: 'demo-authors',
templateUrl: './authors.component.html'
})
export class AuthorsComponent {
public authors: DocumentCollection;
public constructor(private authorsService: AuthorsService) {
authorsService
.all({
// include: ['books', 'photos'],
// fields: {
// authors: ['name']
// }
})
.subscribe(authors => (this.authors = authors));
}
}
```
#### View for this controller
```html
id: {{ author.id }}
name: {{ author.attributes.name }}
birth date: {{ author.attributes.date_of_birth | date }}
```
#### Collection sort
Example: `name` is a authors attribute, and makes a query like `/authors?sort=name,job_title`
```typescript
let authors = authorsService.all({
sort: ['name', 'job_title']
});
```
#### Collection filtering
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.
```typescript
authorsService.all({
remotefilter: { country: 'Argentina' }
});
```
### Get a single resource
From this point, you only see important code for this library. For a full example, clone and see demo directory.
```typescript
authorsService.get('some_author_id');
```
#### More options? Include resources when you fetch data (or save!)
```typescript
authorsService.get('some_author_id', { include: ['books', 'photos'] });
```
TIP: these parameters work with `all()` and `save()` methods too.
### Add a new resource
```typescript
let author = this.authorsService.new();
author.attributes.name = 'Pablo Reyes';
author.attributes.date_of_birth = '2030-12-10';
author.save();
```
#### Need you more control and options?
```typescript
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)
);
```
### Update a resource
```typescript
authorsService.get('some_author_id').suscribe(author => {
this.author.attributes.name += 'New Name';
this.author.save(success => {
console.log('author saved!');
});
});
```
### Pagination
```typescript
authorsService.all({
// get page 2 of authors collection, with a limit per page of 50
page: { number: 2 ; size: 50 }
});
```
#### Collection page
- number: number of the current page
- size: size of resources per page ([it's sended to server by url](http://jsonapi.org/format/#fetching-pagination))
- 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
## Local Demo App
You can run [JsonApi Demo App](http://ngx-jsonapi.reyesoft.com/) locally following the next steps:
```bash
git clone [email protected]:reyesoft/ngx-jsonapi.git
cd ngx-jsonapi
yarn
yarn start
```
We use as backend [Json Api Playground](https://jsonapiplayground.reyesoft.com/).
## Colaborate
Check [Environment development file](DEV_ENVIRONMENT.md) 😉.