> For the complete documentation index, see [llms.txt](https://ibm-developer.gitbook.io/datastage-standalone-workshop/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ibm-developer.gitbook.io/datastage-standalone-workshop/getting-started/lab-rest.md).

# Lab: DataStage: Read JSON from a REST call

You can use the REST protocols to incorporate IBM DataStage Flow Designer features in your custom application. You use the REST protocol to perform actions such as compiling jobs, running jobs, and getting job status.

The following REST calls are supported:

* XML
* JSON

> For more info check out the [REST API](https://www.ibm.com/support/knowledgecenter/SSZJPZ_11.7.0/com.ibm.swg.im.iis.ds.fd.doc/topics/rest_api.html) documentation.

In this lab we'll learn how to call a JSON endpoint and pipe those results to a file using DataStage.

This lab consists of the following steps:

1. [Create job layout](/datastage-standalone-workshop/getting-started/lab-rest.md#1-create-job-layout)
2. [Customize with Assembly Editor](/datastage-standalone-workshop/getting-started/lab-rest.md#2-customize-with-assembly-editor)
3. [Compile and run the job](/datastage-standalone-workshop/getting-started/lab-rest.md#3-compile-and-run-the-job)
4. [View output](/datastage-standalone-workshop/getting-started/lab-rest.md#4-view-output)

## Before you start: Launching DataStage Flow Designer

Before we start the lab, let's switch to the `iis-client` VM and launch `Firefox`.

![Switch to iis-client](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F4af2f82e080f3cf332a10c188968c608c54c7c11.png?generation=1613580975614829\&alt=media)

Launch the desktop client by going to the start menu and searching for `DataStage Designer`.

![DataStage Designer](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F627f2c577fdcb43187153c8175b96a2b3a746379.png?generation=1613580975682951\&alt=media)

## 1. Create job layout

Start a new `Parallel Job` project and create a job that looks like the image below. Remember to wire the elements together. It should have:

* 1 x Hierarchical Data
* 1 x Peek
* 1 X Sequential File

![REST job](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F70c839ce531631182f38aad891d75557fd46c11e.png?generation=1613580989461653\&alt=media)

Double click on the `Hierarchical Data` node and click on `Edit assembly`.

![Edit Hierarchical Data](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F20e5469667fba9cad546378bf524d1124b7770b2.png?generation=1613580976628744\&alt=media)

## 2. Customize with Assembly Editor

The "Assembly Editor" will launch. This allows for fine tuning the properties of certain jobs.

Click on `Palette` and add a `REST` step and a `JSON Parser` step.

![Add Steps](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F804dbb17984c4dd94427f66ec4d48e89e2249c04.png?generation=1613580969667939\&alt=media)

From the `REST` step, in the `General` tab, specify the following URL:

```
http://dummy.restapiexample.com/api/v1/employees
```

![Specify URL](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F0d7ae61a708f73eb8a9289437982b98a16edc436.png?generation=1613580973710473\&alt=media)

From the `REST` step, in the `Response` tab, specify the content type to be `test/plain`:

![Specify content type](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2Fc2ec89a1f541ad962d58ca3a635b71c99e1861ba.png?generation=1613580997586945\&alt=media)

From the `REST` step, in the `Mappings` tab, click on the `Map Automatically` button:

![Specify mappings](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F423deabeaf85e226c849e9b407420985698af687.png?generation=1613580967857295\&alt=media)

Before proceeding to the `JSON Parser` step click on the `Libraries` button on the top left and choose the `New Library` button.

![Create new library](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2Fdd00dde17d5adfe8a88b81e7ee67bcaa025262a2.png?generation=1613580962602026\&alt=media)

Download the file [`employees.json`](https://raw.githubusercontent.com/IBM/datastage-standalone-workshop/master/data/employees.json) to the desktop.

Click on `Import New Resource` and browse to the newly downloaded file.

DataStage will automatically use this file as a JSON schema

![New JSON schema](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2Fc96650df2a803d500f3669fe311d4c2311586e51.png?generation=1613580999608120\&alt=media)

From the `JSON Parser` step, in the `Configuration` tab, choose the `String set` option and use the drop down menu. There is only one result.

![Specify configuration](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2Fd8bf7b4968cdbc6fcb9f8230aac4cc1e33bb239d.png?generation=1613580957693094\&alt=media)

From the `JSON Parser` step, in the `Documentation Root` tab, specify the documentation root to be the new library from the previous step, likely called `employees`.

![Specify documentation root](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F3d504f4f4830d7e1fb8454973c67a575bf5ad027.png?generation=1613580959563207\&alt=media)

From the `Output` step, in the `Mappings` tab, click on the `Map Automatically` button. Remove the `image profile` and any others you do not want to use.

![Specify mappings](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2Fb1a9c5db40ab6e5d40872738168c16cce2641785.png?generation=1613580957432712\&alt=media)

Click `OK` to exit out of the `Assembly Editor`.

## 3. Compile and run the job

Before running the job we need to modify the `Sequential File` by double clicking on its icon on the designer. Specify an output file, say `output.csv`.

![Specify output file](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2Fb7effe37138747fc172b49ceab78273fdcdc12d2.png?generation=1613580972924044\&alt=media)

Also update the columns by adding the `id`, `employee_name`, `employee_salary`, and `employee_age` fields.

![Specify columns](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2Fdb301c95826b01fe871ede4b871103c01b251be9.png?generation=1613581001645600\&alt=media)

Finally, compile and run the job.

> You may see an error message: `Message bundle error Can't find resource for bundle com.ibm.e2.Bundle_E2_engine_msgs, key OperatorException.operatorTransitionFailedAtRuntime`. To resolve this, go to the `iis-server` machine, go to the temp directory `cd /tmp` and delete the XML files `rm -rf XML*`. This should resolve the issue. Re-compile and re-run the job. For more info check out [IBM support](https://www.ibm.com/support/pages/hierarchical-stage-job-fails-message-bundle-error-cant-find-resource-bundle-comibme2bundlee2enginemsgs-key-operatorexceptionoperatortransitionfailedatruntime).

## 4. View output

The output file will be saved on the server. Switch to the server VM by clicking the first icon on the `Environment VMs panel` and selecting `iis-server`. Login as the `root` user with the password `inf0Xerver`.

![Switch to server VM](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F1220da958ddbc17ed19ad67ceb1e6c9639dd7561.png?generation=1597955733364644\&alt=media)

Change your direcotory using `cd` to the location where you had stored the file. If you provided a path starting at "/", then it will be stored at that location in the server. Since we had only provided `output.csv` as the file path in the ***File*** connector, the file will be available in the Transformation project's folder, i.e.,

```bash
cd /opt/IBM/InformationServer/Server/Projects/<project-name>/
```

Finally, output your results using the `cat` command.

```bash
cat output.csv
```

![output file contents](https://1138345240-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MEzw3DrGZcdmHwc51yL%2Fsync%2F0db337d0af38f73f27ad00c887a9cda3a4fa86ae.png?generation=1613580961550164\&alt=media)

**CONGRATULATIONS!!** You have completed this lab!