REST best practice

Working with REST IDs

• When a REST service returns an id, the Jigx local data provider can automatically be synced with this id, eliminating the need to add a sync-entities action to the jig.

• The id property must be added in the outputTransform of the REST data provider function.

• This is useful on a POST (create) as a temp_id is created in the local data provider for the record when it is created. If the id is in the POST function outputTransform, the temp_id is automatically updated with the REST id once it is created on the REST side.

• The below image shows how the local data provider creates a temp_id when a new customer is added. Then, it is automatically synced with the REST id because the id is in the function's outputTransform.

Syncing temp_Id

function.jigx

provider: DATA_PROVIDER_REST
method: POST # Create new record in the backend
url: https://jigx-training.azurewebsites.net/api/customers
useLocalCall: true

parameters:
  x-functions-key:
    location: header
    required: false
    type: string
    value: #Use manage.jigx.com to define credentials for your solution
  firstName:
    type: string
    location: body
    required: true
  lastName:
    type: string
    location: body
    required: true
  companyName:
    type: string
    location: body
    required: true
  address:
    type: string
    location: body
    required: false
  phone:
    type: string
    location: body
    required: false
  email:
    type: string
    location: body
    required: false

inputTransform: |
  {
    "firstName": firstName,
    "lastName": lastName,
    "companyName": companyName,
    "address": address,
    "phone": phone,
    "email": email
  }
# add the id to the output which ensures the local table,
# is automatically updated with the REST id once it is created.
outputTransform: |
  {
    "id": custId,
    "status": status
  }

Where and when to sync and load data

Knowing when to load and sync data is important as it can impact the apps performance and functionality when the device is offline.

• Load data in the index.jigx file by adding an onFocus, and onLoad for performance. This also ensures that all data is available if the device goes offline.

• Add the sync-entity or sync-entities action to a global action, to sync the data with the onFocus or onRefresh events ensuring efficiency and reusability throughout the solution. The global action is referenced in the solution's jigs to sync data from the REST server.

• See REST syncing & loading local Data for an in-depth explanation.

Working with complex REST structures

Working with complex REST objects can be tricky, as they include arrays, nested objects, and other complex data structures. When integrating and manipulating these JSON structures from the REST data provider configure the following:

1. JsonProperties in the SQLite query jsonProperties: - addresses

2. In the expression used to retrieve the value, specify the exact property in the array or nested object that you require by referencing the JsonProperty followed by the property. description: [email protected][0].city leftElement: element: avatar text: [email protected][0].state

JSON

JSON

"customers": [
        {
            "custId": 1,
            "firstName": "Merilyn",
            "lastName": "Bayless",
            "companyName": "20 20 Printing Inc",
            "addresses": [
                {
                    "address": "195 13n N",
                    "city": "Santa Clara",
                    "county": null,
                    "state": "CA",
                    "zip": "95054"
                }
            ],
            "phones": [
                {
                    "mobile": "408-758-5015",
                    "office": "408-758-5015"
                }
            ],
            "email": "[email protected]",
            "web": "http://www.printinginc.com",
            "region": "US West",
            "customerType": "Silver",
            "jobTitle": "Project Manager",
            "logo": null
        },

datasource

Data handling when a device is offline

Dealing with offline remote data is fundamental to ensuring data synchronization and consistency between the mobile app and the remote data source, allowing users to continue using the app and performing actions without interruption. Offline remote data handling explains how to configure solutions to deal with data when the device is offline.

Update multiple records in a single REST call

Updating multiple records in a single REST call helps optimize API usage by reducing the number of requests, which prevents hitting API rate limits and improves performance by minimizing client-server round-trip times. To implement this, use the execute-entities action to call the REST function. There are two configuration methods:

• functionParameters: Use this for static values that are consistent across all records.

• data property: Use this for dynamic values that vary per record.

For more information see Update multiple records in a single REST call.

Use the $ approach in REST functions

Avoid configuring functions and their parameters on a field level, using the dollar approach caters for maintenance and dynamic inclusion when new fields are added to the REST service. The required fields are specified in the jig's datasource.

provider: DATA_PROVIDER_REST
method: GET
url: https://{custom-variable}Appointment
parameters:
  $expand:
    location: query
    required: false
    type: string
    value: Logs
  $filter:
    location: query
    required: true
    type: string
  accessToken:
    location: header
    required: true
    type: token
    value: xxxx
  cloudURL:
    location: path
    required: true
    type: string
outputTransform: $

Using input and output transforms (no fields)

Send one message body parameter into a function, this ensures you do not have to modify the input transform when fields change or are added. Create generic functions, that can be reused in multiple scenarios.

Limit json_extract calls in query SELECT statements

Limit json_extract calls in query SELECT statements except on key fields for example, when using joins, WHERE, ORDER BY which require you to extract a specific field.

• Calling individual field names to bind to components is expensive.

• Use JSON properties on data at the root.

• InstanceIds - use the name of the data in the schema that comes from the REST service.

• Field names - use the name of the data in the schema that you want to send back to the backend system.

Navigation

• Use New & existing behaviour in go-to action

• Use InstanceId

State usage

Solution state has a performance impact, use only when necessary.

Use SQL commands for bulk deletes

Use SQL commands for bulk deletes rather than execute-entities to ensure performance optimization.

Use indexes when joining on json_extracts

ID fields are indexed when joining an adjacent json_extracts, where fields are not indexed SQLite scans through to find the data causing slow performance. Always select id in SELECT statements to ensure optimal performance.

Where to store settings.

• Use custom variables (solution settings > custom in Management) for settings that hardly ever change, for example, server URLs.

• For settings that change frequently use Dynamic Data.

Establish a naming convention for REST functions and files

• Improves readability: Clear names make it easier to understand the purpose of the function or file, e.g., rest-get-appointments.

• Maintainability: Consistent naming simplifies future updates and debugging.

• Collaboration: Common naming standards help multiple contributors understand and interact with the project seamlessly.

See Also

• REST examples