REST Overview

introduction when a rest call returns data to {{jigx}} , the processed json is inserted into a local sqlite database the {{jigx}} mobile application then queries the database, displaying the data on the device this architecture supports offline scenarios data is stored in a document database format {{jigx}} provides a shorthand sql parser to select using logical column names alternatively, you can use the native json extract() function to manipulate the data from sqlite when the result of the output transform is an array of json objects, {{jigx}} will insert each item in the array in its row note that sql is case insensitive while json is case sensitive functions definitions are stored in the functions folder in a {{jigx}} project and are files that end in a jigx file extension when jigx files are created in the functions folder, the {{jigxbuilder}} intellisense code completion is available using ctrl+spacebar we recommend using this capability, as it provides all available code completion options relevant to {{jigx}} functions to add a new function, add a new file in the functions folder, the jigx extension is automatically added for you function file names must be lowercase and may not contain special characters once functions are published in a {{jigx}} solution you can preview the function in {{jigxmanagement}} under the solution's rest functions option see rest functions docid\ ozuk ogm5yr4cxqa4zwyl for more information parameters and authentication support all rest functions support header, path, query, and body parameters in addition, including calling services with no authentication, jigx supports oauth, api key, and basic auth or secrets for authentication the code completion will display the available template options when adding a new function functions code completion options creating a new function using one of these template options adds the skeleton code to the function definition, making it easier to configure functions for specific providers with their authentication configuration these options are rest a rest service call with no authentication that returns json by default rest (api key) a rest service call that includes x api key in the header for authentication rest (basic auth) a rest service call that includes basicauth in the header populated with the credential's information rest (oauth) a rest service call that includes accesstoken (authorization) in the header populated with the oauth token returned during the oauth loop rest (secret) a rest service call that includes a secret that can be added to the header or query string parameters for authentication soap a template for soap calls sql the template for making either query or stored procedure calls to microsoft sql azure rest call function components the following describes the options available when configuring a rest function call rest function options provider data provider rest for making rest service calls methods {{jigx}} supports the following methods when making rest calls delete get head put patch post url the url of the service that must be called {{jigx}} supports path and query parameters in the url path parameters are tagged with curly brackets {} {{jigx}} will replace the path parameters with the values of the parameters defined in the parameter section of the function definition query parameters specified in the url will be removed by {{jigx}} and replaced by parameters defined in the parameters section of the function definition with a location property of type query swagger parser the swagger parser function allows you to convert swagger, open api, and postman collection data to {{jigx}} functions in the {{jigxbuilder}} command to start the swagger parser function is (command + shift + p) generate jigx functions both remote and local files can be used, and only the json format is allowed all files created by the swagger parser function saves in your functions folder variable replacement you can replace variables in your postman collection, for example, replacing the baseurl as you add the value 'google com' to the variable all functions requiring this variable will be updated replace variable function value for variable replacement input transform – detail and examples when the format of the function is specified as json, the body of the call is generated by the input transform the input transform is a jsonata statement ( https //jsonata org https //jsonata org/ ) that can contain parameters defined in the parameter section of the function definition in this example, we are applying the following mapping jigx parameter ordernumberparameter jigx parameter orderdescriptionparameter the values of these parameters are replaced in the input transform to build the json payload which will be submitted to the order rest service parameters in the input transform are specified using their name without quotes an example is inputtransform | $ { “ordernumber” ordernumberparameter, “orderdescription” orderdescriptionparameter } the | character in yaml allows you to format the content of the yaml node over multiple lines output transform detail and examples the output transform is a jsonata expression that transforms the json received by the rest call into the json that will be inserted in the local sqlite tables when the result of the output transform is an array of json objects, jigx will insert each item in the array in its own row then, the values in the json object are selected as data columns in an sqlite statement using the json extract() function sqlite function below is an example of json returned by a rest call and then transformed into an array of json objects { "customerid" "1432", "customername" "johson shipping", "shippingaddress1" "7645 1st street", "shippingcity" "nashville", "shippingstate" "tn", "shippingzip" "78654", "orders" \[ { "ordernumber" "1234", "orderdescription" "printer refil", "ordertotal" 345 67, "customerid" "1432", "orderdate" "1 29 2022" }, { "ordernumber" "654", "orderdescription" "printer paper", "ordertotal" 185 27, "customerid" "1432", "orderdate" "1 29 2022" }, { "ordernumber" "8934", "orderdescription" "envelopes", "ordertotal" 25 88, "customerid" "1432", "orderdate" "1 29 2022" } ] } output transform to get an array of orders $ orders $ is the root of the document and orders the array with the collection of orders the result of the transform is \[ { "ordernumber" "1234", "orderdescription" "printer refil", "ordertotal" 345 67, "customerid" "1432", "orderdate" "1 29 2022" }, { "ordernumber" "654", "orderdescription" "printer paper", "ordertotal" 185 27, "customerid" "1432", "orderdate" "1 29 2022" }, { "ordernumber" "8934", "orderdescription" "envelopes", "ordertotal" 25 88, "customerid" "1432", "orderdate" "1 29 2022" } ] as mentioned above, all order objects in the array will be inserted as individual rows into a sqlite table specified in the datasource section in the {{jig}} definition function parameters function parameters are used to pass data into the function definition from the {{jig}} that uses the function see the datasources docid\ ddg nus2 7g lb9idn4pe section of the documentation parameters are defined by naming them and describing the properties of that parameter parameter names are used when the parameters are referred to in the rest query path or input transforms (see an example above for an inputtransform) function parameter properties location the location determines where the parameter will be applied in the rest call as follows path when path is specified as the location, the parameter is available as a token in the url's path query when query is specified as the location, a query string parameter with a name set to the name of the function parameter will be added to the url the value of the query string parameter is set to the value of the function parameter header when header is specified as the location, a header entry with a name set to the name of the function parameter will be added to the request the value of the header entry is set to the value of the function parameter body when body is specified as the location, the function parameter is available in the inputtransform defined for the function tokens matching the parameter's name will be replaced with the value of the function parameter type type is specific to the rest call being made most types are defined as strings when they are used in path, query, or body locations the available types are string, number, array, object when types are declared in authentication header parameters, they are specific to the authentication type being configured see authentication parameters below required the required value is either true or false this determines whether the parameter needs to be set when the function is used in a {{jig}} 's datasource parameters used in paths must be set to required true or they will generate an error this determines if the rest call requires this parameter if so, set this property to true , alternatively if the parameter is optional, you can set it to false additional properties continuation many rest services limit the number of items that can be retrieved from the service in a single call to retrieve all items associated with a query, additional calls must be made to the service using a url or additional data passed to the caller the caller then makes repeated calls to the service using these continuation parameters to retrieve all records jigx rest functions can be configured to automatically repeat calls to continuation functions by specifying a continuation block in the function yaml the continuation url and parameters overwrite the parameters in the original function call therefore all parameters, including oauth tokens and api keys, must be replicated in the continuation function since the continuation url or parameters are outside of the data returned by the function (at a higher level), the outputtransform of the function will need to be changed to return the records in their own property and the records property specified in the function yaml to locate the output records example microsoft’s graph api uses continuation urls to request the next page of items from their services if there are more items in the response than can be handled in a single call, or the caller has limited the number of items per page, the service will return the @odata nextlink parameter specifying the url to call to fetch the next page of results { "@odata context" "https //graph microsoft com/v1 0/$metadata#users('bb13f9b6 d289 485f 9ae6 76be00f5bab3')/drive/root/children", "@odata nextlink" "https //graph microsoft com/v1 0/me/drive/root/children?$top=2&$skiptoken=ugfnzwq9vfjvrszwx1nvcnrczwhhdmlvcj0xjnbfrmlszuxlywzszwy9twljcm9zb2z0k1rlyw1zk0noyxqrrmlszxmmcf9jrd0yma", "value" \[ { 	 	} ] } all data has been returned when the @odata nextlink parameter is no longer present in the results note in this case that the nexturl expression is used to both check for continuation data as well as the url to fetch the next page of data method get provider data provider rest parameters $top location query type number required false accesstoken location header type microsoft value jigx microsoft oauth required true url 'https //graph microsoft com/v1 0/me/drive/root/children' outputtransform > $ {"nextlink" `@odata nextlink`,"items"\ value {"id"\ id,"name"\ name,"size"\ size,"lastmodifieddatetime"\ lastmodifieddatetime,"type" $exists(folder) ? "folder" "file"}} records =$ items continuation when =$ nextlink url =$ nextlink parameters accesstoken location header type microsoft value jigx microsoft oauth required true error jigx allows you to customize rest endpoint error messages to improve user experience, communicate more effectively, and ensure users understand that errors are not their fault by configuring custom error properties, you can, suppress or customize default error messages, log error details for more effective debugging, and create more robust and user friendly error solutions see rest error handling docid\ w8rh7l4ynu ypssqfosas and rest errors docid\ exlotsui1r7dncuegnxa4 for more information forrowswithvalues by default the return json payload from the rest call replaces previous data in the sqlite database the forrowswithvalues property allows you to update specific values in the sqlite database instead of replacing all rows, providing a better user experience the forrowswithvalues property specifies a key value pair where the key is a json extract() column in the sqlite table that will be matched by the value only rows that match these criteria will be updated the object will be added as a new row to the collection if a match isn't found you can have multiple key value pairs specified under forrowswithvalues think of this as a where clause that {{jigx}} uses when it adds the result of the rest call's outputtransform to the sqlite table the property should be passed as a parameter and be referenced in the outputtransform as shown in the example below forrowswithvalues forrowsinrange similar to forrowswithvalue but instead of matching rows by value the forrowsinrange specifies a key value pair where the key is a json extract() column in the table that a value range will match only rows that match these criteria will be updated the object will be added as a new row to the collection if a match isn't found you can have multiple key value pairs specified under forrowsinrange think of this as a where clause with a between that {{jigx}} uses when it adds the result of the rest call's outputtransform to the table pass the values you want to test as input parameters in this example, minmag and maxmag the property to test is mag this property ( mag ) must appear in the outputtransform then set the range you are testing for in the input parameter ( minmag ) and ( maxmag ) forrowsinrange you can combine forrowswithvalues and forrowsinrange as per the example below you cannot combine forrowswithmatchingids with any other range or value check forrowswithmatchingids similar to forrowswithvalue , when forrowswithmatchingids is specified, {{jigx}} will perform an upsert on a specific id the outputtransform must contain a field called id this id will be used to match the id column in the database; if a record with this id exists, it will be updated if no match is found, the record will be inserted no deletion is performed when forrowswithmatchingids is used summary {{jigx}} will delete all rows from the table matching the forrowswithvalues or forrowsinrange key value pairs before it inserts new results the user interface is only updated once the data action has been completed on the table to avoid flickering of user interfaces the user interface is only updated as the last step see also rest docid\ lej3vf0o4nptfseucllaw offline remote data handling docid\ h36q0e3t93lcbn9wejmjp