https://github.com/abdulhaq-e/ngrx-json-api
A JSON API client for ngrx
https://github.com/abdulhaq-e/ngrx-json-api
ngrx ngrx-json-api
Last synced: 3 months ago
JSON representation
A JSON API client for ngrx
- Host: GitHub
- URL: https://github.com/abdulhaq-e/ngrx-json-api
- Owner: abdulhaq-e
- License: mit
- Created: 2016-07-23T00:54:15.000Z (about 9 years ago)
- Default Branch: master
- Last Pushed: 2023-01-06T01:56:36.000Z (almost 3 years ago)
- Last Synced: 2025-07-12T00:49:55.785Z (3 months ago)
- Topics: ngrx, ngrx-json-api
- Language: TypeScript
- Size: 1.99 MB
- Stars: 62
- Watchers: 5
- Forks: 27
- Open Issues: 42
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ngrx-json-api
[](https://circleci.com/gh/abdulhaq-e/ngrx-json-api)
[](https://badge.fury.io/js/ngrx-json-api)
[](https://coveralls.io/github/abdulhaq-e/ngrx-json-api?branch=development)
**A JSON API client library for ngrx.**
**Note: v1.0 of the library is compatible with old releases of @ngrx tools (< 2). The current version (>= 2) is compatible with the latest versions of @ngrx platform (>= 4)**
## Documentation
- [Store Structure](./docs/store_structure.md)
- [Service Overview](./docs/service_overview.md)
- [Actions](./docs/actions.md)
- [Basic Usage](./docs/basic_usage.md)
- [Advanced Usage](./docs/advanced_usage.md)
## Getting Started
**1. Install the library:**
```
npm i ngrx-json-api --save
```
Install the dependencies:
```
npm i --save @ngrx/effects @ngrx/store rxjs-compat
```
**Note:** `rxjs-compat` is only needed if you are using `rxjs >= 6.0.0`
**2. Define the resources:**
```ts
import { ResourceDefinition } from 'ngrx-json-api';
const resourceDefinitions: Array = [
{ type: 'Article', collectionPath: 'articles' },
{ type: 'Person', collectionPath: 'people' },
{ type: 'Comment', collectionPath: 'comments' },
{ type: 'Blog', collectionPath: 'blogs' }
];
```
Note that if the type of a resource matches its `collectionPath` in the URL, then no resource definition is necessary.
**3. Import `NgrxJsonApiModule` providing the above definitions and the API url.**
Make sure `StoreModule` and `HttpClientModule` are imported beforehand.
```ts
@NgModule({
imports: [
BrowserModule,
/* other imports */
HttpClientModule,
StoreModule.forRoot(reducers, {}), // reducers, initial state
NgrxJsonApiModule.configure({
apiUrl: 'http://localhost.com',
resourceDefinitions: resourceDefinitions,
}),
],
declarations: [AppComponent],
bootstrap: [AppComponent]
})
export class AppModule {}
```
**4. Inject `NgrxJsonApiService` into the component:**
```ts
import { Component } from '@angular/core';
@Component({
selector: 'my-component',
})
export class MyComponent {
constructor(private ngrxJsonApiService: NgrxJsonApiService) {}
}
```
**5. Use the service to interact with the JSON API server and/or state:**
For example, to read data from the server and display this data in the view:
```ts
import { Component, OnInit } from '@angular/core';
import {
NgrxJsonApiService,
QueryResult,
NGRX_JSON_API_DEFAULT_ZONE,
Query,
Direction
} from 'ngrx-json-api';
import { Observable } from 'rxjs';
@Component({
selector: 'my-component',
template: `{{ queryResults | async | json }}`
})
export class MyComponent implements OnInit {
public queryResult: Observable;
constructor(ngrxJsonApiService: NgrxJsonApiService) { }
ngOnInit () {
// a zone represents an independent json-api instance
const zone = this.ngrxJsonApiService.getZone(NGRX_JSON_API_DEFAULT_ZONE);
// add query to store to trigger request from server
const query: Query = {
queryId: 'myQuery',
type: 'projects',
// id: '12' => add to query single item
params: {
fields: ['name'],
include: ['tasks'],
page: {
offset: 20,
limit: 10
},
// SortingParam[]
sorting: [
{ api: 'name', direction: Direction.ASC }
],
// FilteringParam[]
filtering: [
{ path: 'name', operator: 'EQ', value: 'John' }
]
}
};
zone.putQuery({
query: query,
fromServer: true // you may also query locally from contents in the store, e.g. new resource
});
// select observable to query result holding the loading state and (future) results
const denormalise = false;
this.queryResult = this.ngrxJsonApiService.selectManyResults(query.queryId, denormalise);
}
}
```
The service is the main API for using `ngrx-json-api`. The fetching methods return an `Observable` with the obtained resources stored in a `data` property.
## Example application
For an example application have a look at https://github.com/crnk-project/crnk-example. It combines `ngrx-json-api`
with [Crnk](http://www.crnk.io) as JSON API server implementation to gain a JSON API end-to-end example.
[@crnk/angular-ngrx](https://www.npmjs.com/package/@crnk/angular-ngrx) is further used to facilitate binding
of Angular forms and tables to JSON API. More information can be found at http://www.crnk.io/releases/stable/documentation/#_angular_development_with_ngrx.
## Upgrading from v1.0
Upgrade from v1 is really easy; two simple steps:
1. Remove `storeLocation` from `NgrxJsonApiModule` configuration. It's not needed anymore!
2. Remove `NgrxJsonApiReducer` from `StoreModule` configuration.
3. Import `HttpClientModule` in the application.
# THANKS :heart:
This library wouldn't exist without all the ngrx libraries along with the docs and tools provided with each. Thanks to Ngrx/[Store](https://github.com/ngrx/store),[Effects](https://github.com/ngrx/effects). Also, the basis of this library is [redux-json-api](https://github.com/dixieio/redux-json-api) and [devour](https://github.com/twg/devour) so a huge thanks to the developers of both these JSON API client libs.