Hey everyone! Today we are looking at using different parameters within the REST Connector to either give additional options during running the map, pass through header information on any request, or to allow for bulk adjustments on the setup of the endpoints/methods themselves.
This article is aimed at users who have worked with the REST Connector inside of SmartConnect before, and are looking to either modify an existing provider or create their own definition.
The first time we would use a parameter is if we want to send header data through for the method we are calling. Most often this will be the Authorization parameter or something similar.
In the screenshot above, I have opened the Authorization parameter for my Shopify connection definition. The “Is Header” flag is marked on the parameter and I’ve set a “Default Value” for it. Now when this parameter is added to a particular method, it will automatically pass through its default value when the method is called. Again, this is most commonly used with the Authorization parameter for headers – but if you find an API that requires additional header parameters then this same process can be used for each.
Parameters can also be used as part of the method URL. The first occasion you would use them would be to simplify the process for changing the URL path – whether you are just switching instances within a system or are moving from a dev to production API.
Continuing with the Shopify API, the base URL for any methods would look similar to the following:
https://eOneStore.myshopify.com/admin/
The actual method ends would then change on the end of that URL to call customers.json, products.json, etc. The base URL will change from client to client, however, as the subdomain that is currently called “eOneStore” will be different for every instance. Rather than hardcoding the value in the API definition, we will use a parameter as a placeholder.
In the screenshot above, we have set up each URL to use the {Store_Prefix} parameter as a placeholder for the subdomain. We have added both the Store_Prefix and Authorization parameters to the method as well so SmartConnect knows to reference them when calling the method.
In the background of the screenshot, you can see that every method in my definition is set up in this manner. Now when we export this definition and import it to another system – or if we just need to change the subdomain from a dev instance to production – we no longer have to update each method. Instead, we just switch to the Parameter tab and update the Default Value for the Store_Prefix parameter.
Parameters can also be used on a method when needing to filter the data being returned. These parameters can be changed at runtime on the map – either manually or through a script.
The following method is used to return orders from Shopify:
https://{Store_Prefix}.myshopify.com/admin/orders.json?status=any
That URL has the subdomain URL added to it, but is not using a parameter for the query portion of the URL “?status=any”. If we leave the URL set to this, we can’t update the status filter without changing the definition setup. Instead, we will make a new parameter called “status” and insert it into the URL like we did with the subdomain.
The {status} parameter now has a default value of “any” which will be used if we don’t change anything on the map we use it in. It is also placed into the URL so the value for the parameter will be used in the filter.
When we select that method in a map we now get the option to change and set the parameters in use:
Any parameter used in a method that is not marked as a Header parameter can be updated or changed within the map. In this case, we could change the value of the status being passed through to adjust the records returned.
