@drieam/api

@drieam/api

@drieam/api is middelware for redux. This library handles async AJAX request against Drieam or Canvas Restful APIs.

Usage

Show instructions

$ yarn add @drieam/api redux

1. 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) },
   }
 },
};

1. 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),
});

1. 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 */)]));

1. 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

Examples

 { 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.

Examples

 { 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 or entity should be defined. If both are not defined or false, redux will complaint with an error.

Examples

 { 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, or include. 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.

Examples

```jsx { 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; // Error of unsuccessfully loaded data; otherwise, null errors: [{ // Error messages from the middleware or nothing code: number // HTTP [status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). message: string // Error message. errors: {} // Key-Values error messages. }]; status: number; // Last Maximun HTTP [status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) from the ErrorMessages. links: { next?: { // The link relation for the immediate next page of results. page: number, url: srting, }, last?: HeaderLink // The link relation for the last page of results. first?:HeaderLink // The link relation for the first page of results. prev?:HeaderLink // The link relation for the immediate previous page of results. }; perPage: number; // The amount of item per page. count: number; // The total number of available elements. filters: QueryParams; // An object of the enabled filters. } ```

• apiReducers..entity: Redux Store of a fetched entity.

Examples

{
  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.