@drieam/api
v9.0.0
Published
Default Drieam api wrapper
Downloads
118
Keywords
Readme
@drieam/api
@drieam/api is middelware for redux. This library handles async AJAX request against Drieam or Canvas Restful APIs.
Usage
$ yarn add @drieam/api redux
- Create your api routes configuration:
import { Base } from '@drieam/api';
class User { public id: number; public name: string; }
export type API = { users: User };
const apiRoutes: ApiRoutes<API> = {
users: {
path: '/lti/proxy/api/v1/users/:id?',
mapper: User,
list: true,
options: {
onError: (action) => { console.error(action.response.error) },
}
},
};
- Setup your main reducer configuration:
import * as api from '@drieam/api';
import { combineReducers } from 'redux';
import { apiRoutes, API } from './api';
export const rootReducer = combineReducers({
api: api.reducers.connect<API>(apiRoutess),
});
- Connect to your store:
import { createStore, applyMiddleware } from 'redux';
import * as api from '@drieam/api';
import { apiRoutes } from './api';
import rootReducer from './reducers/index';
const store = createStore(rootReducer, applyMiddleware([...api.apiMiddlewares(apiRoutes, /* options */)]));
- Use your API actions
import * as api from '@drieam/api';
import { API } from './api';
const base = api.actions.connect<API>(apiRoutes, options);
dispatch(base.users.fetchEntity(1))
ApiRoutes
Routing Structure is base of a key-value object where you can configure your basic reducer structure for use cases where you need to fetch data from Rest APIs. This structure is base on a type and a Hash object from that type.
- path: The API type is a reference between your resource and the class used by the middleware to instantiate it. Path-to-Regexp
{ path: '/lti/proxy/api/v1/users/:id?' }
{
path: path => [
'/api/v1/categories',
path.id && path.id,
path.sorting && 'sort'
].filter(Boolean).join('/');
}
}
- mapper: The model class to be instantiated by the middleware. It can be a generic class or custom.
{ mapper: User } // User is a class
{ mapper: data => data }
- list: As true sets the base ListState reducer but you can pass a custom reducer.
- entity: As true sets the base EntityState reducer but you can pass a custom reducer base on that one.
Note: Whether
list
orentity
should be defined. If both are not defined or false,redux
will complaint with an error.
{ entity: true, list: true }
{ list: (state, action) => { return state } }
- options.rowKey (default:
'id'
): collection's unique key. - options.csrfToken: Cross-site request forgery token.
- options.insert: (default:
'append'
) Order of insertion a listState. - options.updateMethod: (default:
'PUT'
) Set the default update method. - options.credentias: (default:
'same-origin'
) The request credentials you want to use for the request:omit
,same-origin
, orinclude
. To automatically send cookies for the current domain, this option must be provided. - options.nestedPayloadKeySuffix: (default:
'Attributes'
) A string to transform the collection name before sending. - options.headers: (default:
{}
) HTTP headers allow the client and the server to pass additional information with the request or the response. An HTTP header consists of its case-insensitive name. - options.form: (default:
redux-form
) Return a specific submission error format.antd
: Antd Forms error format.final-form
: Final-form error format.redux-form
: Redux-form error format. (Deprecated)false
: default by the api.
- options.onSuccess: Callback called by the middleware when a successful api call is made.
- options.onError: Callback made by the middleware when an error occurs.
Actions
Creates an object
structure with all the redux actions needed for each resource definition.
const actions = api.actions.connect<{ users: any }>(api);
- getRequest(filters, apiOptions): Creates a request action depending of the filter properties:
- default parameters is FETCH_LIST
- filters.page is present then FETCH_PAGE
- filters[rowKey='id'] is present then FETCH_ENTITY
- fetchEntity([id, filters, apiOptions]): Creates an action to fetch an entity object.
- fetchList([filters, apiOptions]): Creates an action to fech a collection of entities.
This action refresh the data in the reducer.
- fetchPage([{ page }: filters, apiOptions]): Creates an action to fetch a page of a entity object collection.
This page is added in the reducer.
- fetchNextPage([filters, apiOptions]): Equivalent of
fetchPage({ page: 'next' })
. - saveEntity(attributes[, filters, apiOptions]): Creates an action which saves or updates an entity object.
- deleteEntity(attributes[, filters, apiOptions]): Creates an action to delete an entity object.
- saveList(ids, attributes[, filters, apiOptions]): Creates an action which updates a collection of entity objects. The
attributes
can be one or many and it will be update per id position. Ex:actions.user.saveList([1, 2], { name: 'Peter' });
- deleteList(ids, [, filters, apiOptions]): Creates an action which delete a collection of entity objects.
Reducers
Creates an object
structure with all the redux actions needed for each resource definition.
const apiReducers = api.reducers.connect<{ users: any }>(api);
- apiReducers..list: Redux Store of a fetched list.
- apiReducers..entity: Redux Store of a fetched entity.
{
pending: boolean = false // True if data is still being loaded for the first time.
fulfilled: boolean = false // True if data was loaded successfully.
rejected: boolean; = false // True if data was loaded unsuccessfully.
settled: boolean; = false // True if the data load completed, if successfully or unsuccessfully.
value: T | null = null // Value of successfully loaded data; otherwise, null.
reason: string = null // Error of unsuccessfully loaded data; otherwise, null
status: number = null // Last HTTP [status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes).
}
Contributing
We welcome all contributors who abide by our Code of Conduct. Please see the Contributors Guide for more details on submitting a PR, setting up a local dev environment, running tests, etc...
Versioning
Until this project reaches a 1.0 milestone, minor version numbers will simply be incremented during each release. The Changelog will continue to document the different types of updates, including any "breaking changes".
After the 1.0 milestone, this project will follow SemVer.