Build Custom API Profile

Build a custom API profile for the DataSync Custom API connector. This guide covers both basic (flat) and advanced (nested) API response scenarios. The basic example uses country data from the REST Countries API. The advanced examples use data from Alphavantage.

Type	Description
Basic flat attributes	Attributes are accessible directly at the root of the JSON object (no nesting). Recommended for simple API responses like REST Countries data.
Advanced nested data	Attributes are nested within elements, require handling variable RepeatElements, or include arrays/lists. Typical in finance, analytics, or more complex APIs.

Basic API profiles (flat attributes)

Start a new API profile

Open a text editor such as Notepad.

Copy and paste the following starter XML into your new 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">

Replace the title and desc attributes with values related to your API.
The title value must exactly match the .rsd file name when you save—this acts as the table name and unique identifier for extraction.
Example:
```
<api:info xmlns:other="http://apiscript.com/ns?v1" title="Countries" desc="Canada, France">
```
Save your file with a .rsd extension.

Retrieve and analyze API data

Visit the API documentation, e.g., REST Countries API.
Copy the endpoint URL (e.g., https://restcountries.com/v3.1/all).
In Postman, create a new GET request and send it.
Review the API response. For basic APIs, attributes are at the root of the JSON object.

Define table attributes in the API profile

Define attributes under the <api:info ...> section as follows:

<attr name="X" xs:type="X" readonly="true" other:xPath="X"/>

Replace each X with the appropriate values.

Repeat the <attr .../> line for all attributes you want in your table.

Example:

<attr name="name"         xs:type="string" readonly="true" other:xPath="name.common"/>
<attr name="tld"          xs:type="string" readonly="true" other:xPath="tld"/>
<attr name="status"       xs:type="string" readonly="true" other:xPath="status"/>
<attr name="area"         xs:type="integer" readonly="true" other:xPath="area"/>
<attr name="population"   xs:type="integer" readonly="true" other:xPath="population"/>
``

Attribute value guidelines

Value	Description
`attr name="X"`	Attribute name, typically matching the related JSON field in the API. Example values: `name`, `capital`, `region`
`xs:type="X"`	Data type for the attribute in the API. For example, use `string` for text and `integer` for numbers.
`readonly="true"`	(Optional) Indicates the attribute is read-only. Default for all attributes.
`other:xPath="X"`	XPath or path to the attribute in the API. For root-level attributes, use their name; for nested data, specify the path.
`Specific Property`	Add property attributes here if needed, such as `key="true"` to designate a primary key.

Set global parameters and script methods

Set the content type after your attributes:

<api:set attr="ContentType" value="application/json" />

Define the script method and complete the script block:

<api:script method="GET">
  <api:set attr="method" value="GET" />
  <api:set attr="uri" value="https://restcountries.com/v3.1/all" />
  <api:set attr="RepeatElement" value="/" />
  <api:call op="apisadoExecuteJSONGet">
    <api:push/>
  </api:call>
</api:script>
</api:script>

Complete and use the API profile

Save your .rsd file.
Follow Custom API Source Connector to create and configure your DataSync connection.

Example

<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="Countries" desc="Canada, France">
    <attr name="name"         xs:type="string" readonly="true" other:xPath="name.common"/>
    <attr name="tld"          xs:type="string" readonly="true" other:xPath="tld"/>
    <attr name="status"       xs:type="string" readonly="true" other:xPath="status"/>
    <attr name="area"         xs:type="integer" readonly="true" other:xPath="area"/>
    <attr name="population"   xs:type="integer" readonly="true" other:xPath="population"/>
  </api:info>
  <api:set attr="ContentType" value="application/json" />
  <api:script method="GET">
    <api:set attr="method" value="GET" />
    <api:set attr="uri" value="https://restcountries.com/v3.1/all" />
    <api:set attr="RepeatElement" value="/" />
    <api:call op="apisadoExecuteJSONGet">
      <api:push/>
    </api:call>
  </api:script>
</api:script>

Advanced API profiles (nested and complex attributes)

Advanced API profiles are used when attributes are nested, when recordsets (RepeatElements) are not at the root, or when working with arrays, lists, or variable keys.

Pattern	Description
Nested repeat element	Recordset is nested under an element, not at the root (e.g., `"Realtime Currency Exchange Rate"`).
Variable repeat element	Recordset is under a parent element and its child keys are variables, such as date stamps (e.g., `"Time Series FX (Daily)"`).
Arrays and lists	Attributes are arrays or lists; each array element is identified by a numeric index (e.g., `"Features[0]"`).

Define an API profile when RepeatElement is nested

Prepare your .rsd file as in the basic setup.
In the API response, identify the element containing your records. (For example: "Realtime Currency Exchange Rate".)
Set the RepeatElement value to the name of the recordset, in this format: /ElementName/. For example: /Realtime Currency Exchange Rate/.
For attributes with special characters, spaces, or accents, place the exact value in square brackets [ ] in the other:xPath section.
Save your file and follow Custom API Source Connector to create and configure your DataSync connection.

Example

API response (in Postman)

{
    "Realtime Currency Exchange Rate": {
        "1. From_Currency Code": "USD",
        "2. From_Currency Name": "United States Dollar",
        "3. To_Currency Code": "JPY",
        "4. To_Currency Name": "Japanese Yen",
        "5. Exchange Rate": "106.00200000",
        "6. Last Refreshed": "2020-07-24 13:17:15",
        "7. Time Zone": "UTC",
        "8. Bid Price": "-",
        "9. Ask Price": "-"
    }
}

Attribute definition (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]"/>

Full API profile example

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
    <!--Sets the table name and description and contains the column definitions-->
    <api:info xmlns:other="http://apiscript.com/ns?v1" title="CurrencyUSD" desc="Currency USD">
      <attr name="From_Currency Code" xs:type="string"   readonly="true"  other:xPath="[1. From_Currency Code]"/>
      <attr name="From_Currency Name" xs:type="string"   readonly="true"  other:xPath="[2. From_Currency Name]"/>
      <attr name="To_Currency Code"   xs:type="string"   readonly="true"  other:xPath="[3. To_Currency Code]"/>
      <attr name="To_Currency Name"   xs:type="string"   readonly="true"  other:xPath="[4. To_Currency Name]"/>
      <attr name="Exchange Rate"      xs:type="decimal"  readonly="true"  other:xPath="[5. Exchange Rate]"/>
      <attr name="Last Refreshed"     xs:type="datetime" readonly="true"  other:xPath="[6. Last Refreshed]"/>
      <attr name="Time Zone"          xs:type="string"   readonly="true"  other:xPath="[7. Time Zone]"/>
    </api:info>
    <!--Setting global parameters-->
    <api:set attr="ContentType" value="application/json" />
    <api:script method="GET">
      <api:set attr="method" value="GET" />
      <api:set attr="uri" value="https://www.alphavantage.co/query?function=CURRENCY_EXCHANGE_RATE&from_currency=USD&to_currency=JPY&apikey=demo" />
      <api:set attr="RepeatElement" value="/Realtime Currency Exchange Rate/" />
      <api:call op="apisadoExecuteJSONGet">
          <api:push/>
      </api:call>
    </api:script>
</api:script>

Define an API profile when RepeatElement is a variable

Use this method when data records are grouped under a parent element, and each group's key is variable (for example, dates).

Prepare your .rsd file as in the basic setup.
In the API response, locate the parent element and identify the variable child keys (such as dates). For example: "Time Series FX (Daily)".
Set the RepeatElement value to /ParentElement/%/, where % represents the variable portion (for example: /Time Series FX (Daily)/%/).
For attributes with special characters, spaces, or accents, place the exact value in square brackets [ ] in the other:xPath section.
Complete, save, and register your profile.

Example

API response (in Postman)

{
    "Meta Data": {
        "1. Information": "Forex Daily Prices (open, high, low, close)",
        "2. From Symbol": "CAD",
        "3. To Symbol": "USD",
        "4. Output Size": "Compact",
        "5. Last Refreshed": "2020-07-28 11:25:00",
        "6. Time Zone": "UTC"
    },
    "Time Series FX (Daily)": {
        "2020-07-28": {
            "1. open": "0.7495",
            "2. high": "0.7499",
            "3. low": "0.7462",
            "4. close": "0.7465"
        },
        "2020-07-27": {
            "1. open": "0.7447",
            "2. high": "0.7493",
            "3. low": "0.7440",
            "4. close": "0.7493"            
        },
        "2020-07-24": {
            "1. open": "0.7461",
            "2. high": "0.7473",
            "3. low": "0.7433",
            "4. close": "0.7452"            
        },
    }
}

Attribute definition (in Notepad)

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

Full API profile example

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
    <!--Sets the table name and description and contains the column definitions-->
    <api:info xmlns:other="http://apiscript.com/ns?v1" title="Forex" desc="To retrieve Forex data">
      <attr name="open"   xs:type="decimal"   readonly="true"   other:xPath="[1. open]"/>
      <attr name="high"   xs:type="decimal"   readonly="true"   other:xPath="[2. high]"/>
      <attr name="low"    xs:type="decimal"   readonly="true"   other:xPath="[3. low]"/>
      <attr name="close"  xs:type="decimal"   readonly="true"   other:xPath="[4. close]"/>
    </api:info>
    <!--Setting global parameters-->
    <api:set attr="ContentType" value="application/json" />
    <api:script method="GET">
      <api:set attr="method" value="GET" />
      <api:set attr="uri" value="https://www.alphavantage.co/query?function=FX_DAILY&from_symbol=CAD&to_symbol=USD&apikey=demo" />
      <api:set attr="RepeatElement" value="/Time Series FX (Daily)/%/" />
      <api:call op="apisadoExecuteJSONGet">
          <api:push/>
      </api:call>
    </api:script>
</api:script>

Define attributes for arrays and lists

If your data includes arrays or lists (such as email addresses or features), declare each array element using its zero-based index in brackets.

important

For array or list data in your API, define each value by its zero-based index, for example Features[0] and Features[1].

Example

API response

{
    "UserName" : "russellwhyte",
    "FirstName" : "Russell",
    "LastName" : "Whyte",
    "MiddleName" : null,
    "Gender" : "Male",
    "Age" : null,
    "Emails" : ["Russell@example.com","Russell@contoso.com"],
    "FavoriteFeature" : "Feature1",
    "Features" : ["Feature1","Feature2"],
    "AddressInfo" : [
        { 
            "Address" : "187 Suffolk Ln.",
            "City": {
                "Name" : "Boise",
                "CountryRegion" : "United States",
                "Region" : "ID"
            }
        }
    ]
}

API profile definition (in Notepad)

<!--Sets the table name and description and contains the column definitions-->
<api:info xmlns:other="http://apiscript.com/ns?v1" title="People" desc="Get all the people">
    <!--Individual column definitions-->
    <attr name="UserName"        xs:type"string"   readonly="true"   other:xPath="UserName"/>
    <attr name="FirstName"       xs:type"string"   readonly="true"   other:xPath="FirstName"/>
    <attr name="LastName"        xs:type"string"   readonly="true"   other:xPath="LastName"/>
    <attr name="MiddleName"      xs:type"string"   readonly="true"   other:xPath="MiddleName"/>
    <attr name="Gender"          xs:type"decimal"  readonly="true"   other:xPath="Gender"/>
    <attr name="Age"             xs:type"datetime" readonly="true"   other:xPath="Age"/>
    <attr name="Emails"          xs:type"string"   readonly="true"   other:xPath="Emails"/>
    <attr name="FavoriteFeature" xs:type"string"   readonly="true"   other:xPath="FavoriteFeature"/>
    <attr name="Feature1"        xs:type"string"   readonly="true"   other:xPath="Features[0]"/>
    <attr name="Feature2"        xs:type"string"   readonly="true"   other:xPath="Features[1]"/>
    <attr name="Address"         xs:type"string"   readonly="true"   other:xPath="AddressInfo/Address"/>
    <attr name="City"            xs:type"string"   readonly="true"   other:xPath="AddressInfo/City/Name"/>
    <attr name="CountryRegion"   xs:type"string"   readonly="true"   other:xPath="AddressInfo/City/CountryRegion"/>
    <attr name="Region"          xs:type"string"   readonly="true"   other:xPath="AddressInfo/City/Region"/>
</api:info>

Basic API profiles (flat attributes)​

Start a new API profile​

Retrieve and analyze API data​

Define table attributes in the API profile​

Attribute value guidelines​

Set global parameters and script methods​

Complete and use the API profile​

Example​

Advanced API profiles (nested and complex attributes)​

Define an API profile when RepeatElement is nested​

Example​

API response (in Postman)​

Attribute definition (in Notepad)​

Full API profile example​

Define an API profile when RepeatElement is a variable​

Example​

API response (in Postman)​

Attribute definition (in Notepad)​

Full API profile example​

Define attributes for arrays and lists​

Example​

API response​

API profile definition (in Notepad)​

Basic API profiles (flat attributes)

Start a new API profile

Retrieve and analyze API data

Define table attributes in the API profile

Attribute value guidelines

Set global parameters and script methods

Complete and use the API profile

Example

Advanced API profiles (nested and complex attributes)

Define an API profile when RepeatElement is nested

Example

API response (in Postman)

Attribute definition (in Notepad)

Full API profile example

Define an API profile when RepeatElement is a variable

Example

API response (in Postman)

Attribute definition (in Notepad)

Full API profile example

Define attributes for arrays and lists

Example

API response

API profile definition (in Notepad)