It exports a few things, the most important being 'API'.
API handles quite a bit:
- it knows about the RESTful structure of our back-end and thus knows which endpoints map to which actions.
- it knows about our redux store and therefore is able to save the results automatically to the store
- it handles caching of the index endpoint by sending the latest updated_at value to the back-end (gets this through redux)
- it allows for easy after/before effects for all CRUD actions
Most important methods:
index, create, update, destroy
Parameters:
For every method, the first parameter is 'kind', the pluralized name of the resource you're working, with, eg 'posts' or 'users'.
Second argument is an object with possible keys:
| Key | Explanation | Default value |
|---|---|---|
| ignoreStamp | do not send last updated stamp (disable caching) | |
| inverted | Flip directions: get all records updated BEFORE stamp | |
| localKind | The local redux 'kind', useful if you want to save it differently in your local store than it's called in your back-end | |
| refresh | Ignore caching & reset redux store | |
| params | extra params to be sent with the request | {} |
Create/update share the exact same parameters. The first argument is kind, the second 'params' (the data you wanna send) which is automatically converted to Rails' strong parameter style, as: {record_name: data} and the third is an object again with all other options:
| Key | Explanation | Default value |
|---|---|---|
| local | If local is false, it will only save it in the back-end but not in the local redux store | true |
| localKind | The local redux 'kind', useful if you want to save it differently in your local store than it's called in your back-end | |
| extraParams | extra params which will be inserted at the top level | {} |
Destroy takes an id as a second argument, and accepts an object with as only key extraParams to be included at the top-level of your data.
Examples:
const users = API.index("users") ## will get only new users
const users = API.index("users", {refresh: true}) ## will reset the redux store and fetch all fresh users from the back-end
const newUser = API.create("users", {name: 'Amazing guy', fat: false})
const updatedUser = API.update("users", {id: 4, fat: true}) ## you have to insert the ID when updating
API.destroy("users", 1) # destroy always goes by id
Backend is actually just an apisauce instance, with which you can do everything you can do with apisauce. It adds a few niceties:
- Headers needed for JSON communication
- Auto inserting of access token
- Dispatching start_load & end_load to the store for every non-get request so you can show a loading indicator
- Handles & displays errors
NOTE: If you want to prevent the library from dispatching loading actions or prevent the lib from showing the success message, add doNotLoad: true to either the data or headers of your request.
It exports a few selectors for easy interaction with your redux store. All selectors take the store as the first argument and the kind as the second argument. The most important are:
Find a record by a query (NOTE: is like Rails' find_by)
useSelector(state => find(state, 'users', {id: 4}) ## gets user 4
useSelector(state => find(state, 'users', {activated: true, name: 'Jordan'}) ## gets user who's actived and whose name is Jordan
Identical to find in usage but returns multiple records
Returns all records for a given kind
useSelector(state => all(state, 'users')
Takes an object as third parameter with start and end as keys and returns all records within that date range.
useSelector(state => all(state, 'posts', {start: "2020-01-01", end: "2020-12-31"})
NOTE: for this to work, your record should have a 'date' field.
Returns all records with at least one match, useful for finding associated records & querying array fields.
useSelector(state => includes(state, 'users', {team_ids: [1]}) Will return all users who have 1 in their team_ids array.
NOTE: where would find all users whose team_ids value is EXACTLY EQUAL to [1]