Customizing your API

This section is for users who want to customize an API profile to meet their specific needs.

You can either create an API profile from scratch or edit an existing profile by retrieving only the data you are interested in. This data uses values (keys) from attributes to build and define the table columns. In both cases, you need to map your API profile to the API provider through its URI address.

Before starting, make sure that you have file archive software such as WinZip, 7-zip or Winrar installed on your computer to extract tables from the API profile.

Note

Tables (.rsd files) are included in API profile files (.apip extension) where API profiles are understood by the system as .zip files.

.rsd type files are schema files used to:

  • Input parameters regarding the management of the Endpoints in the API.
  • Define how rows are displayed in the table.
Tip

We highly recommend you to install the Postman software to help you in this process, as it gives you a clear view of the API Profile structure (i.e., how attributes are nested). Click here to download the software for free.

Setting up Postman

When Postman is installed, open it and perform these steps so that Postman can retrieve data of unlimited size. This change is only required the first time you use Postman.

  1. In the upper right-hand corner, click the settings icon (wrench key) and select Settings.

  2. Under the General tab, in the Max Response Size in MB field, set the value to 0.

  3. Click the X to save your change.

Understanding the .rsd file structure

Before creating the custom API profile, you first need to understand what elements this file is composed of.

<api:script>
	<api:info>
		<attr/>
	</api:info>
	<api:set attr="ContentType" value="application/json" />
	<api:script method="GET" >
		<api:set attr="method" />
		<api:set attr="uri" />
		<api:set attr="RepeatElement" />
		<api:set/>
		<api:call>
			<api:push/>
		</api:call>
	</api:script>
</api:script>

Tag Description
<api:script>

The first <api:script> tag acts as the <body> tag in an HTML file.

Its values can be understood as the one you find in the <head> tag in an HTML file, i.e, its metadata remain the same.

<api:script xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:api="http://apiscript.com/ns?v1" >
<api:info>

This tag sets the table name and description through the title and desc parameters.

It also contains the parameters proper to columns called Attributes (attr). The attributes which can be used differ from one API provider to another but three parameters remain mandatory: name (name), data type (xs:type) and the path (other:xPath).

<api:info xmlns:other="http://apiscript.com/ns?v1" title="Countries" desc="A List of Countries">
     <attr name="name"         xs:type="string"  	readonly="true"     other:xPath="name.common"/>
     <attr name="status"       xs:type="string"  	readonly="true"     other:xPath="status"/>
     <attr name="area"         xs:type="integer"  	readonly="true"     other:xPath="area"/>
</api:info>

For the data type (xs:type), here is a list of the most used values:

  • xs:type="string": Enter "string" to retrieve data containing characters, line feeds, carriage returns, and tab characters.
  • xs:type="decimal": Enter "decimal" to retrieve data containing numeric values (ex: 9.12).
  • xs:type="integer": Enter "integer" to retrieve data containing integer values (ex: 9).
  • xs:type="date": Enter "date" to retrieve data containing the date in the YYYY:MM:DD format (YYYY for the year, MM for the month and DD for the day).
  • xs:type="time": Enter "time" to retrieve data containing time in the hh:mm:ss format (hh for hours, mm for minutes and ss for seconds).
  • xs:type="datetime": Enter "datetime" to retrieve data containing date and time in the YYYY-MM-DDThh:mm:ss format (YYYY for the year, MM for the month, DD for the day, T for start of time section, hh for hours, mm for minutes and ss for seconds).
<api:set>

Within the first <api:script> tag, Global Parameters are defined.

<api:set attr="ContentType" value="application/json" /> = indicates the type of content that will be returned by the API. This value never changes.

<api:set attr="RepeatElement" value="/" /> = is used when the data to be retrieved are not accessible directly from the root level, i.e., there is a sub-level (refer to Common Steps and Information for more details). If so, replace the "/" with the name of the element as Value; this is explained in further details in Specific Steps to Advanced Case.
<api:script>

The second <api:script> tag refers to the HTTP method that will be executed by the script.

<api:script method="GET" >

A <api:set> tag is required to implement the method (refer to the row below for more details).

<api:set>

The <api:set> tags within the second <api:script> tag is used to implement the HTTP method and defines from which URL address (URI) the data should be retrieved.

For the HTTP methods, you can use:

  • GET: Corresponds to SELECT

  • POST: Corresponds to INSERT

  • PUT/PATCH /MERGE: Correspond to UPDATE

  • DELETE

GET is the most used method.

<!-- For the HTTP Method -->		
  <api:script method="GET" >
    <api:set attr="method" value="GET" />
  <!-- To define the source (URL) from which the data come from --> 
    <api:set attr="uri" value="https://restcountries.com/v3.1/all" />

<api:call>

This tag is used to call operations through the op parameter. It will be followed with the <api:push> tag to display (push) the result in DataSync. Authorized operations differ from one API provider to another.

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