How to Access the GoodData API Directly
Our tutorial How to Create Your First Visualization with GoodData UI SDK showed how you can create a simple web app with the GoodData UI SDK in a few minutes. For the sake of simplicity, that tutorial includes using a local proxy that enables the app to call the GoodData APIs without the need to address cross-origin requests. Using a proxy is not a best practice for creating production-ready apps. Instead, we recommend that you use Cross-Origin Resource Sharing (CORS). Setting up CORS allows you to develop and run web applications that can communicate directly with the GoodData APIs.
This tutorial does _not_ address authentication. The easiest way to make sure that your API requests to the GoodData platform are authenticated is to be logged into your white-labelled domain in the same browser you are using for your local development.
Step 1. Get a white-labeled GoodData domain
By default, you access the GoodData Portal via https://secure.gooddata.com
. If you white-label the GoodData Portal URL, you can have it at, for example, https://analytics.yourcompany.com
.
In general, a white-labeled domain enables you to remove branding elements from the GoodData Portal and optionally replace them with branding from your enterprise. For more information, see White Labeling.
White-labeling is done by the GoodData Support specialists per request submitted via the GoodData Support Portal.
You can white-label a brand new domain (see White-Label a New Domain) or an existing domain (White-Label an Existing Domain).
If you are contacting GoodData Support regarding white labeling your domain, you may want to also request CORS as described in Step 2 of this tutorial.
Step 2. Configure CORS
To request CORS setup, submit a request via the GoodData Support Portal. In your request, provide the following:
- The name of your GoodData domain
- URLs the you want to enable requesting additional URLs to enable API calls from a local machine during development is recommended. For example,
https://local.test:8443
(you have to set uplocal.test
as an alias forlocalhost
because using the actual localhost is not allowed).
Example:
If your white-labelled GoodData domain is analytics.example.com
and your app is expected to be hosted at https://smart-app.example.com/
, you can request CORS by submitting the following request:
To: support@gooddata.com
Subject: CORS origin setup for analytics.example.com
Hello GoodData Support team,could you please enable https://smart-app.example.com and https://local.test:8443 as CORS origins for the GoodData domain associated with https://analytics.example.com/
Thank you.
If you know the exact name of your GoodData domain, provide it too.
Step 3. Update your code
Before your app starts communicating with GoodData, add the following lines to your executable code (for example, at the beginning of the file with your root component):
import { config } from 'gooddata';
config.setCustomDomain('https://analytics.example.com');
If you followed the instructions from the tutorial [How to Create Your First Visualization with GoodData UI SDK]ht_create_your_first_visualization.md), you can now remove the proxy-related code from the package.json
file because it is not needed anymore.
Step 4. Run your app locally without a proxy
In this step, we assume the following:
You have requested CORS settings that allow access (besides others) from
https://local.test:8443/
.You have set up your network so that
local.test
is an alias of your development environment.If you are developing on a Mac or Linux machine, add
local.test
to the end of the line starting withc127.0.0.1
in your/etc/hosts
file (you may need administrator/root privileges for that). Here is an example of how the/etc/hosts
file may look on a Mac:## # Host Database # # localhost is used to configure the loopback interface # when the system is booting. Do not change this entry. ## 127.0.0.1 localhost. 255.255.255.255 broadcasthost ::1 localhost
In this example, local.test
was added by you, and everything else is the original contents of the /etc/hosts
file. If you have not added anything else to the file besides appending local.test
to the right line, you can ignore the initial comment provided by the operating system about not changing the /etc/hosts
file.
Do _not_ modify the /etc/hosts
file except for adding local.test
to the end of the line starting with 127.0.0.1 unless you are absolutely sure that you know what you are doing.
- Make sure that your browser accesses your app via
https://local.test:8443
instead ofhttps://localhost:8443
. If you use react-scripts (for example, you followed the instructions in the tutorialHow to Create Your First Visualization with GoodData UI SDK), set theHOST
environment variable tolocal.test
before starting the app. To do so, run the following command from the command line:
HTTPS=true HOST=local.test PORT=8443 yarn start
Step 5. Deploy your app
In this step, we assume that your app's address is https://smart-app.example.com
.
Create a production build of your app, and deploy it on your server.
The process is similar to deploying any other application.
- Identify the target URL.
If your app is going to be deployed under a specific folder (for example,
https://smart-app.example.com/my-first-app
), add the following line to yourpackage.json
:
"homepage" : “https://smart-app.example.com/my-first-app",
You can skip this step if your app will be accessible directly from the root folder (that is, directly via https://smart-app.example.com/
).
- Create a production build:
yarn build
- Upload the contents of your build folder to your production server, and point your browser to the target URL.