Creating a custom API Profile

In this document, two cases of API creation will be discussed according to their difficulty level, i.e., how Attributes are nested.

For the simple case, the data related to the countries frrom REST Countries will be used, as the tree structure is easy to understand and simple (attributes are at the root level) for building and consolidating your knowledge base.
For the advanced case, the data related to Foreign Currency Exchange (ForEX) from Alphavantage API will be used to discover what is involved when the attributes are not at the root level.

Common Steps and Information

Open a text editor such as Notepad and copy and paste the following lines into your document:

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
<api:info xmlns:other="http://apiscript.com/ns?v1" title="A Title" desc="A Description">

For the title and desc values, enter a title and a description (preferably related to the information you want to retrieve from the API).
Save your document as a .rsd file.

Important
The value of the title attribute that you enter in the <api:info> tag must be identical to the file name when saving the file. This value is used to define the table name and is the unique identifier of the Web API when adding a table for an extraction.

Example

Go to the documentation section of the API provider. In this case it is the REST Countries API.
Copy the URI address which contains the data you are interested in. In this example, All Data (https://restcountries.com/v3.1/all) is chosen so that all data can be retrieved.
In Postman, click the + next to the Overview tab to create a new request.
In the GET field, paste the URI address and click Send.
As you can see from the image below, the attributes are accessible directly from the root; there is no element name prior the "{" sign.
Returning back to your Notepad, add the following line to create the columns of the table.
```
<attr name="X"               		xs:type="X"  	readonly="true"     other:xPath="X"/>
```
To make it easier to define the values, place Postman on one of the side of your screen and the Notepad on the other side.

Replace the X values as follows:

attr name="X"	Replace the "X" with a name (preferably) linked to the data that will be retrieved from the other:xPath section. In this example, it would be name, capital, region, etc.
xs:type="X"	Replace the "X" with the data type of the attributes listed in the API. In this example, it would be string if name or tld is chosen as attribute or integer if population or area is chosen (refer to Understanding the .rsd file structure for further details regarding the list of data types).
readonly="true"	The property assigned to this attribute. In this case, this property does not add anything special and is completely optional (by default, all attributes are read).
other:xPath="X"	Replace the "X" with the path where the attribute is located in the API. In this example, since the attributes are located at the root level, just repeat their name as value for the xpath.
Specific Property	If you need to add a property, this will be at this location you should insert it. For example, if you want to assign a Primary Key to an attribute you could add key="true".

Duplicate this line to add as many attributes as you want and change the values according to their data type as presented in the table above.
Once your list of attributes is complete, close it by adding the </api:info> tag.

Example

Copy and paste this line in your Notepad to set up the global parameters.
```
<api:set attr="ContentType" value="application/json" />
```

Copy and paste the following lines to define the script method that will be used.

<api:script method="GET" >
	<api:set attr="method" value="GET" />
	<api:set attr="uri" value="X" />
	<api:set attr="RepeatElement" value="X" />

Replace the X values as follows:

api:set attr="uri" value="X"	Replace the "X" with the same URI address you pasted in Postman to get the data. In this example, it would be https://restcountries.com/v3.1/all.
api:set attr="RepeatElement" value="X"	Replace the "X" with a "/" since the data in this example are retrieved from the root level (there is no attribute name prior the "}"). Refer to Specific Steps to Advanced Case if there is a repeated element (attribute) containing items with space in their names or if there is an array among the items you want to retrieve the data from.

Copy and paste the following lines in your Notepad to finish the creation of your custom API.

<api:call op="apisadoExecuteJSONGet">
	<api:push/>
     </api:call>
   </api:script>
</api:script>

Example

Once the .rsd file is completed:
1. Follow the procedure described in Custom API Settings to create and configure a new connection.
2. Follow the procedure described in Adding an Extraction and Setting Up the Extraction to define the extraction.
3. Follow the procedure described in Running an Extraction to retrieve the data.

Specific Steps to Advanced Case

For this section, we use the data related to Foreign Currency Exchange (ForEX) from Alphavantage API as the attributes are not at the root level.

This section is composed of two examples: the first example is about data retrieval from a RepeatElement which is not at the root level and the second one is about retrieving data when the RepeatElement is a variable.

First Example

Repeat the steps described in Common Steps and Information until step 7.

As you can see from the image below, the attributes are not accessible directly from the root, i.e., there is an element name prior the "{" sign. In this case, the element name is Realtime Currency Exchange Rate.
Use the steps described in Common Steps and Information from step 9 until the end to build your API profile.
For the api:set attr="RepeatElement" value="X" tag, replace X with the value displayed before the "{" sign in the following format: /value/. In this case, it is Realtime Currency Exchange Rate.

If the attributes have special characters such as an underscore, spaces, or words with accents, place the value as is into square brackets [ ] in the other:xPath section.

In Postman Becomes In Notepad


other:xPath="[1. From_Currency Code]"/>
other:xPath="[2. From_Currency Name]"/>
other:xPath="[3. To_Currency Code]"/>
other:xPath="[4. To_Currency Name]"/>
other:xPath="[5. Exchange Rate]"/>
other:xPath="[6. Last Refreshed]"/>
other:xPath="[7. Time Zone]"/>

Example

Once the .rsd file is completed:
1. Follow the procedure described in Custom API Settings to create and configure a new connection .
2. Follow the procedure described in Adding an Extraction and Setting Up the Extraction to define the extraction.
3. Follow the procedure described in Running an Extraction to retrieve the data.

Second Example

In this section, we explain how to retrieve data which is not at the root level and when the RepeatElement is a variable.

Repeat the steps described in Common Steps and Information until step 7.

As you can see from the image below, the attributes are not accessible directly from the root, i.e., there is an element name prior the "{" sign, followed by random dates acting as a variable, as they are incremented automatically. In this case, the element name is Time Series FX (Daily).
Use the steps described in Common Steps and Information from step 9 until the end to build your API profile.
For the api:set attr="RepeatElement" value="X" tag, replace X with the value displayed before the "{" sign in the following format: /value/. In this case, it is Time Series FX (Daily) followed with "/%/" to declare that the dates are variables.

If the attributes have special characters such as an underscore, spaces, or words with accents, place the value as is into square brackets [ ] in the other:xPath section.

In Postman Becomes In Notepad


other:xPath="[1. open]"/>
other:xPath="[2. high]"/>
other:xPath="[3. low]"/>
other:xPath="[4. close]"/>

Example

Important

If some items are presented as an array or a list as in the example below in the other:xPath section, you will have to declare each element by placing them in square brackets[ ] and replacing their value with numbers starting with 0.

In the API provider documentation	Becomes	In Notepad
	=

Once the .rsd file is completed:
1. Follow the procedure described in Custom API Settings to create and configure a new connection.
2. Follow the procedure described in Adding an Extraction and Setting Up the Extraction to define the extraction.
3. Follow the procedure described in Running an Extraction to retrieve the data.