Connecting with the JSON No Code and JSON No Code OAuth connectors

​

What are these connectors?

The JSON No Code and JSON No Code OAuth connectors allow you to connect Domo to REST APIs that return data in a standard JSON format. The connectors support standard authorization methods such as Basic Authentication, API key, Bearer Token or OAuth 2.0.

​

What you must know before you start?

The information needed to power up a JSON or JSON OAuth connector is typically contained in the API documentation of the system you are trying to read. Specifically, you must know:

1. How to authenticate to the API.
2. The base URL for the API.
3. A list of API endpoints that can be called, and which includes:
   1. The URL for each endpoint.
   2. Any required path parameters or query parameters, along with any optional path or query parameters for each endpoint.
4. Pagination requirements
5. Any rate limits imposed by the API.

​

Prerequisites to configure the connector

If you are trying to connect to an API, you will need the following to power up either connector:

1. Access to the API documentation of the API you are trying to connect.
2. Credentials to access the data source. You must be able to read the documentation to determine how to authenticate to the API.

​

Configuring the Authentication mechanism in the JSON NoCode Connector

The JSON No Code Connector supports the following mechanisms to authenticate to an API:

1. Basic Authentication - Use this option if the API you are connecting to requires a username and password to authenticate.
2. API Key - Use this option if you have to pass a single String as an authenticator to the API, either as a parameter or as a header field.
3. No authentication - Use this option if the API you are connecting does not require authentication to call the endpoints, or if you are uploading a file in JSON format.

​

Configuring the authentication method in the JSON No Code OAuth connector

The JSON No Code OAuth connector supports 2-legged and 3-legged standard OAuth implementations. Refer the API documentation for the system you are connecting to, to determine which option you need to select. Mostly you will be asked to configure an app on the system you are trying to connect to. The app will request for a redirect URL. For this connector, use https://oauth.domo.com/api/data/v1/oauth/providers/json-oauth/exchange.

​

Getting data from the API

Note: This section assumes that you are able to successfully authenticate to the API in question. Configuring the connector to point to the correct API endpoint is done in the Data Selection pane of the connector. The Data Selection pane has three sections that need to be configured: (1) Connection Type (required) (2) Request Type (required) (3) Advanced Settings (optional)

​

Connection Type

First, you will be asked how to connect to the JSON file, and then, based on your selection, you will be prompted for further details. The below screenshot and table shows the available connection options, and when to use them.

Connection Option	When to use this option	Required information
Upload file containing JSON data	Your data is in a file in JSON format Your file is not accessible via HTTP, HTTPS or via SFTP. Your data is static and will be manually updated.	Location of file to upload on local disk.
File Transfer (SFTP)	Your data is in a file in JSON format. Your file is accessible via an SFTP site that supports Basic Authentication.	The username and password for the SFTP site. The URL to connect, which consists of the SFTP server and the file path.
HTTP Request	Your data is accessible via an API that returns data as a JSON formatted response Your data is not static and can change Your data is not stored in a file	The URL of the API endpoint to connect. The authentication mechanism required by the API. Any headers that you will need to be sent in the request. Input dataset ids, if you are using the Dynamic Parameters or Dynamic URL mode

​

Connecting via HTTP Request

Connecting via HTTP Request to an API, allows you to call an API on a schedule, and get the freshest data available. The documentation for the API you are trying to connect to, will include information on how to make a request to the API.

​

Add header

If the documentation specifies that you need to add a header to any calls to API endpoints, you can add the header and the specified value by selecting the +ADD HEADER button. (Note: Not all APIs require headers in the request.) Once you select the +ADD HEADER button, you’ll be able to specify the name of the header as the Key, and the value of the header to add as the Value. The API documentation should provide this information. For example, if the API documentation specifies that you need a header called “ Required_header ” with a value of “ My_First_Header ”, you should enter the following: You can add as many headers as required by the API and as mentioned in the API documentation.

​

Specifying the request type

API endpoints either require parameters as query parameters at the end of the URL, for example, https://api.endpoint?query_parameter=some_value, or as part of the URL, for example, https://api.endpoint/parameter_value. The HTTP request connection type allows you to call an API endpoint once with static parameter values or no parameter values, or multiple times with different parameter values. To determine if the endpoint you are trying to connect to requires parameter or query values, refer to the API documentation. The below table shows when to use which request type. The examples refer to Domo’s own API, documented at https://developer.domo.com/portal/8ba9aedad3679-ap-is.

Request type	When to use this request type	Example
Single URL	Use this request type when: You only want to call this endpoint once, and/or Any path or query parameter values are static, with the exception of date parameters.	https://domo.com/api/groups/v1{” ”}
Dynamic URL	Use this request type when: The API endpoint requires a parameter in the path, for example, the <groupId> value in the example URL, and You want to call this endpoint multiple times with different values of the path parameter in the same dataset. for example, if you would like to call the endpoint once for groupId =2, once for groupId = 3, once for groupId = 4.	https://domo.com/api/groups/v1/&lt;groupId&gt;{” ”};
Dynamic parameters	Use this request when The API endpoint requires a query parameter, and You want to call this endpoint multiple times but with different query parameter values every time. For example, if you want to call the endpoint once with the groupName=”Eastern Sales”, and then again with the groupName=”Northern Territories”	https://domo.com/api/v1/activites?groupName=&lt;groupName&gt;{” ”};

​

Configuring the Dynamic URL request type

The Dynamic URL option should be used if you need to call the same endpoint multiple times, and the endpoint in question has the following format. https://base_url/<path parameter>/end_of_url OR https://base_url/<path_parameters>; To configure the connector to call an endpoint multiple times with different path parameter values each time:

1. Set the JSON File URL value to the part of the API that occurs before the path parameter.
2. If the endpoint has a URL component after the path parameter, add everything after the path parameter to Paste at the end of the URL box.
3. In the “values location”, indicate whether you would like the connector to replace the “path parameter” with values from a static list defined in the connector itself, or if you would like the connector to lookup the values to be used from a dataset that you define.

The following table has sample JSON File URL and Paste at the end of the URL configurations:

Endpoint definition	JSON file URL	Path parameter	Paste at the end of the URL
https://domo.com/api/groups/v1/{group_id}{” ”}	https://domo.com/api/groups/v1/{” ”}	group_id
https://api.domo.com/v1/streams/{STREAM_ID}/executions{” ”}	https://api.domo.com/v1/streams/{” ”}	stream_id	/executions

Configuring the list of values to use for the path parameters is done in the Values location section. To use a static list of values in each call to the endpoint, select “Enter the values to loop through” option, and provide a comma separated list of values. For example, in the following screenshot, the connector is configured to call the https://domo.com/api/groups/v1/ endpoint 4 times, replacing the {group_id} with the values 1,2,3, and 4 each time the connector runs. If you need to use a more dynamic list of values as the path parameter value, you can have the connector read the values from a dataset, using the “Use values from an existing dataset” option. Selecting this option will prompt you to select the dataset that has the values, as well as the column in the dataset that has the values to iterate over. Note: The connector will not validate the format of the values in the column selected.

​

Configuring the Dynamic Parameters request type

The Dynamic Parameters option should be used if you want to call the same endpoint multiple times, and the endpoint in question has the following format. https://base_URL?query_parameter=<some_value> To configure the connector to call an endpoint multiple times with values for the same query parameter key each time do the following:

1. Set the JSON File URL value to the part of the API endpoint that occurs before the ?query_parameter string.
2. Set the Parameter Key to the query_parameter. Do not include the “?”.

Configuring the list of values to use for the path parameters is done in the Values location section. As with the dynamic path request type, you can provide the list of values the connector should use for the query parameter on each call as either a static list or by looking up the values of a column in a dataset.

​

Additional options

Skip Values if the API call fails At times, APIs are designed to throw an error if an endpoint in the API is called using an invalid path or query parameter value. E.g. the endpoint https://my.api.com/<number> might only accept the values of 1, 2, or 3 for <number> and may throw an error if any other value is used for <number>. Usually, if a connector receives an error response from an API, the connector execution will stop and an error message is logged in the DataSet History tab. If you are using the Dynamic URL or the Dynamic parameters option to call an endpoint multiple times, it is possible that your list may contain an invalid value that causes an API error. The “Skip values if the API call fails” checkbox will force the connector to ignore any errors that are due to the API rejecting a particular parameter value. This allows the connector to loop through all dynamic parameters until the end of the list without the connector failing on a bad value. For example, if the connector is configured to https://api.domo.com/v1/<project_id> and the API throws an error if an invalid project_id is passed. If the connector is configured to use the following static list of values for <project_id> in this order: 12, abcd, and 34, and if abcd is not a valid value for the project_id, having the Skip Values if API call fails option selected, will allow the connector to proceed with the next value in the list, that is, it will move to 34. If the option is not selected, then the connector will stop after receiving the error and will not try to call the endpoint again.

​

Add dynamic value to data

This option is available only in the Dynamic Parameters and Dynamic URL request types. If this option is checked, the connector will append a column that indicates the value of the path parameter or query parameter used to generate a row of data. In this manner, a user can correlate the API result with the dynamic value used in the call which generated the row. If this option is checked, you will be required to provide a name for the column which cannot be the same as the name of any other column in the dataset. If you are unsure what column names the API will return, you can either:

1. Review the schema in the Parsing section of the connector, OR
2. Run the connector to get a dataset with the schema.

​

Add Body

This option is available to use with all request types. If the API documentation specifies a payload must be included in the body of the request, you can use the Add Body option to specify a static payload. Add Date Parameter This option is available to be used with all request types. Use this option if the endpoint you are connecting to, supports filtering by date as a query parameter, and you would like to specify a date range or window to pull data. Note: The connector are unaware if an endpoint supports date filtering, so you cannot validate the format of the date parameter. However, if you use this option, check the API documentation to determine which date format the endpoint is expecting. Add Parameter This option is available to be used with all request types. This option allows you to specify one or more query parameters with static values, that are used every time the endpoint is called. No matter how many times the endpoint is called in a connector run, the value of the parameters configured in this section will not change. The connector will return all the data available for that endpoint in the Data Preview section.

​

Advanced Settings

The Advanced Settings section of the connector allows you to configure additional requirements by the API. The below table provides some guidelines on the options available, but you must check your API documentation to determine if any options apply.

Option	Purpose
Does your JSON text requires a line reader?	If the JSON returned by the API has multiple lines, select “Yes” for this option, or select “No”. You can determine whether the JSON has multiple lines by Looking at the API documentation. Looking at the Data Preview in the Parsing section.
Should backslash characters be escaped?	Select “Yes” if your data includes blackslash (“\n”) characters.
How will you provide the certificate?	Select one of the available options if the API you are connecting to requires a certificate to connect. Check your API documentation to determine how to get the certificate if needed.
Do you need to enter a rate limit for this API?	Use this option if the API you are connecting limits how many calls to the API you can make over a given period of time. Check your API documentation for this value. You can provide the limit as calls per second, calls per minute or calls per hour.

​

Using the URL Preview Pane

The URL Preview Pane allows you to preview the call the connector will make on each run. Note that the preview does not show any Authorization headers such as API keys, tokens or username/passwords. In the case of a Single URL, the preview will be static. For example if the connector is configured as shown below: Then the URL preview will appear as follows: If you select Dynamic URL or the Dynamic Parameters option, and if you select the values as a static list, then the URL preview will show a sample call with one of the values. Hovering over the value shows a preview of the entered list. An example is shown in the below screenshot:

​

Known Limitations

1. When you use Dynamic URL or the Dynamic parameter option, you can only specify one variable to use. You cannot use more than one dynamic variable, unless one of the variables is a date filter.
2. When you sue the Dynamic URL or the Dynamic parameter options, you may only use a dynamic path parameter or a dynamic query parameter. At present, you cannot construct a URL that combines both.

​

Error Messages and Troubleshooting

1. I am looping through a dataset and my connector is failing with an error 429. What is causing this error and what should I do? This error occurs when the API you are connecting to has a rate limit, and you have exceeded that rate limit. This may not happen when you are using the single URL endpoint, as you are only making one call in this case. However, when you use the Dynamic URL or the Dynamic Parameters endpoint, you are making multiple calls to the API. To fix this: (i) Check your API documentation to see what rate limits are available (ii) Set the rate limit in the Advanced Section in the connector.
2. I am using the Dynamic Parameters or the Dynamic URL request type, and I get a 401 error when the connector runs. This error usually occurs when you are making an API call and you do not have access to that endpoint. This error can happen when you are using a static or a dynamic request type. If you are using a dynamic request type, it is possible that only particular dynamic values are generating this error. To troubleshoot, do the following:
   1. Check the “Skip values if API call fails” and “Add dynamic value to data” options. The “Skip values if API call fails” option will allow the connector to ignore a failed call and go to the next dynamic value. This will allow you to determine whether the error is being generated by one particular dynamic value or if the error is due to overall access to the endpoint. The “Add dynamic value to data” option will let you see which dynamic values are not generating an error, so you can later determine which input dynamic values are bad. Don’t forget to add a column to the dataset to store the parameter value.
   2. Run the connector again.
   3. Check the dataset. If the dataset is not blank, then one or more dynamic parameters were generating the error. Check the column you created to store the parameter value used for each call against the input dataset using a dataflow to determine which parameters caused the error. If the dataset is blank, then either the base endpoint you are calling does not exist or your credentials do not have access to the endpoint.