Using APIs

If transporters existed, we wouldn't use it for good. We'd just transport our crap right out of our bodies.


Getting Started

Node Served Reactium

Scenario 1: You are using the out of the box node.js server that comes with Reactium.

If you are planning on using the default node.js server, and if you have a primary REST API URL that you will be using throughout your Reactium app, Reactium provides a http proxy behavior. This can come in handy to avoid complex CORS (Cross Origin Resource Sharing) configuration on your API server.

By default, any XHR (REST API call) to /api will automatically be proxied to your REST API.

The address Reactium will proxy to is set by environment variable: REST_API_URL

Environment Variable

1
2
3
# Cause Reactium to proxy /api to https://example.com
export REST_API_URL=https://example.com
npm start

There is a module started to help you get started at src/app/api/config

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
let apiConfig = {};

// the api from the browser's perspective
if (typeof window !== 'undefined') {
    apiConfig = {
        parseAppId: window.parseAppId,
        restAPI: window.restAPI,
    };
    // the api from the server's perspective
} else {
    apiConfig = {
        parseAppId: process.env.PARSE_APP_ID || 'Actinium',
        restAPI: process.env.REST_API_URL || 'http://demo3914762.mockable.io',
    };
}

export default apiConfig;

Note that there is a browser context apiConfig, and a server context apiConfig. This configuration file is automatically imported by node.js to specify the target of the proxy.

In case you are wondering why the REST_API_URL environment variable is used, instead of simply changing the restAPI property directly, this makes your node.js server configurable for different environments by environment variable when deployed. For instance, you may have a local, dev, qa, and production API url.

This configuration is also used for Server-Side-Render, so that data can be pre-fetched by the server to runtime prerender your React routes on the server.


Direct API

Scenario 2: API URL provided by window.

If you are not planning on using the built in node.js server, You will probably wish to set the restAPI parameter to reference your API directly.

Direct API: src/index-static.html

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
<!DOCTYPE html>

<html>
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
        <link rel="stylesheet" href="/assets/style/style.css">
    </head>
    <body>
        <div id="router"></div>

        <script>
            window.ssr        = false;
            // change below to override window property
            // window.restAPI    = '/api'; // uncomment to have browser proxy through node.js
            window.restAPI    = 'https://example.com/'; // to have browser connect directly
            window.parseAppId = 'Actinium';
        </script>
        <script src="/assets/js/vendors.js"></script>
        <script src="/assets/js/main.js"></script>
    </body>
</html>

src/index-static.html is used when building your Reactium site to be deployed as static assets. By setting, window.restAPIin your static html file to the URL to your REST API, you will be able to have have your app connect directly. Note that you will be responsible for handling CORS yourself in your API server.

For local development, you will auto want to make these changes in your feo.js (Front-End Only) template.


Parse SDK

You may have noticed the parseAppId configuration. Reactium is primed and ready for you to begin working with Parse SDK https://docs.parseplatform.org/js/guide/

To begin working with your own Parse API, specify the REST_API_URL and PARSE_APP_ID environment variables.

$ export REST_API_URL=https://my.parse.url/api
$ export PARSE_APP_ID=MyApp
$ npm start

There is a default helper module provided to immediately begin using the Parse SDK. The use this in your code:

Some services.js file

1
2
3
4
import Parse from 'appdir/api';
export default {
    cloudFunction: params => Parse.Cloud.run('myCloudFunction', params),
};