Below is a short overview of the pieces involved in making an API request and processing its data. For more detailed instructions, please consult one of the detail pages listed below.

Prerequisites

Before getting started with this section, it is recommended to familiarize yourself with the following subjects:

• Redux.js The basics of how actions and reducers work in Redux.js
• reselect What a selector is and how to use it

Gateway

The Gateway.js module contains the Gateway utility which is hte util that eventually creates and executes the API requests. We do not interact directly with this utility in our application code. Instead we use the helper actions in the apiActions directory.

apiActions

We execute API requests in our application code through the utility actions provided in the common/src/app/actions/resources/apiActions directory. This contains the following files:

• apiRequest.js Contains the most low-level api actions. They can be used to make simple API calls that do not need any processing (like a POST or DELETE). The apiRequest() action creator will use Gateway to make the actual API request. The other action creators (apiGet(), apiPost(), apiPut(), etc...) are just helper actions that pre-fill the method parameter. See Basic API requests
• apiGetEntity.js Can be used to do a GET request for a single entity and process the result. See Getting an entity from the API
• apiGetCollection.js Can be used to do a GET request for a list of entities and process the result. See Getting a collection from the API
• apiGetEntityList.js This file is deprecated
• getDefaultApiEntityTransform.js When using apiGetEntity and apiGetCollection, it is possible to provide a function that transforms entities before they are stored in Redux state. By default, a transform function is created using this module.

Reducers

We aim to store the data from the API in a standardized way. For that reason, we generally re-use the same reducers for storing such data.

• entities The entities reducer can be found on the root of the Redux state. Entities are stored in a two-dimensional map: first by type, then by id. This is done automatically by the apiGetEntity() and apiGetCollection() actions. Because there is only a single entitiesReducer, there is no need to create a new one for each API call. Other parts of the state should not contain any entities. Rather, they should reference entities in this reducer by type and id. This is a common pattern in Redux known as normalizing state.
• collections Lists of entities are stored under the collections key in the root Redux state.

Sidenote: please be aware that form state is stored separately in form reducers. See Forms and validation.