REST Object¶

Overview¶

REST Objects allow Vinyl developers to make use of a REST APIs in a similar fashion to Vinyl Data Objects. REST Objects support the following:

• CRUD operations
• Integration with various Vinyl Controls such as Multi-Row/Single-Row Panels, Lists
• Custom Events
• Sorting
• Filtering (OData style filter query string)

For REST APIs that support CRUD style operations, configuring a REST Object can be an easy way to integrate an API with your Vinyl app.

CRUD Endpoints¶

For a CRUD style REST API you will want to configure Endpoints that allow records to be Created, Read, Updated, and Deleted. In general this means setting up the following Endpoints:

Vinyl REST API Example Configuration¶

The steps below demonstrate how to configure CRUD endpoints for a Vinyl REST server. In this example we will assume there exists a table such as:

This REST API is exposed from the "northwinds" endpoint as a resource called "customers". Thus the URL to hit this endpoint would be:

https://api.example.com/rest/v1/northwinds/customers

Ensure you've set up the REST API on your server and created the REST Data Source before continuing.

Read Endpoint¶

• Navigate to IDE > Data Servers > Your REST Data Server > Details
• Click + Endpoint on the Endpoints panel and configure the following information:
  • Name: customers (get)
  • Endpoint: customers
  • Method: GET
• Click Save
• Click Discover
• Go back to the previous page
• Select your customers (get) endpoint
• Notice that there are three Output tables
• Double click the customers (get)/items table
• Set the customerId column as the Primary Key
• Ensure the columns are using the expected storage type
• Click Results and verify the returned data is as expected

Create¶

• Navigate to IDE > Data Servers > Your REST Data Server > Details

• Click + Endpoint on the Endpoints panel and configure the following information

  • Name: customers (insert)
  • Endpoint: customers
  • Method: POST

  • Sample Input - Vinyl expects the input to be in the following format:

    {
      "item": {
        "customerId": "abcde",
        "name": "Test Customer",
        "daysActive": 10
      }
    }
    

• Click Save

• Click Discover
  • Note that clicking Discover more than once can cause a primary key violation as the 'abcde' record will already exist on the server. If this happens, you will need to delete the existing record before Discover will work. Either delete the record on the Vinyl REST API server or set up and import the "Delete" endpoint.
• Go back to the previous page
• Select your customers (insert) Endpoint
• Double click the customers (insert) table
• Set the customerId column as the Primary Key
• Set the customerId, name, and daysActive columns to Input/Output direction.
  • When we create a record we pass in all three columns (Input). The Vinyl REST API server echoes these columns in the returned JSON (Output). If for some reason the server echoed back a different value than we sent in (perhaps formatting a string), we will want our record to contain the returned values.
• Ensure the columns are using the expected storage type

Update¶

• Navigate to IDE > Data Servers > Your REST Data Server > Details
• Click + Endpoint on the Endpoints panel and configure the following information
• Name: customers (update)
• Endpoint: customers/{{item/customerId}}
• Method: POST

• Sample Input - Vinyl expects the input to be in the following format:

  {
    "item": {
      "customerId": "abcde",
      "name": "Test Customer (updated)",
      "daysActive": 10
    }
  }
  

• Click Save

• Click Discover
• Go back to the previous page
• Select your customers (update) endpoint
• Double click the customers (update) table
• Set the customerId column as the Primary Key
• Set the customerId, name, and daysActive columns to Input/Output direction.
• Ensure the columns are using the expected storage type

REST Object¶

Once your CRUD Endpoints have been configured, you can create the REST Object.

Create REST Object¶

• Navigate to IDE > Data Servers > Your REST Data Server > Details
• Click More > Super Objects
• Click + REST Object
• Name your REST Object... we'll assume Customers
• Click the checkmark icon to save
• Click the pencil edit icon
• Enable Insert, Update, and Delete by clicking, as appropriate
• Click proceed or the checkmark icon to save

Configure Single Comp¶

• Click the Open Record icon for the REST Object
• Click the Single Comp icon
• Add the customers (get)/items table to the Tables panel
• Click the "*" button to add all of the columns
• Double click the customerId column and set as a Primary Key
• Go through each column in turn and set the Logical Data Type appropriately
• Note that if you click Results before setting up the Many Comp (below) you will get a "No sequence" error message. You will need to configure the Many object first.
• Return to the REST Objects screen

Configure Many Comp¶

• Click the Many Comp icon
• Add the customers (get)/items table to the Tables panel
• Click the "*" button to add all of the columns
• Set the Target columns to their corresponding column names
• Double click the customerId column and set as a Primary Key
• Click Results and verify that you see the appropriate data
• Return to the REST Objects screen

Configure CRUD Endpoints¶

For each CRUD operation list, configure the Endpoint and Bindings as per the table below:

You should now be able to click the Results button on your REST Object and add/delete/update rows.

Custom Events¶

REST Objects can define custom events similarly to other Vinyl Data Objects. To add a custom event to your REST Object you will need to:

• Create a custom event Endpoint
• Create a CRUD Rule to insert into the Endpoint
  • You will need an application configured with the datasource
• Add a custom event to the REST Object

Create Custom Event Endpoint¶

In Vinyl, a custom event on a table can be called by using this URL notation:

https://example.com/rest/v1/northwinds/mytable(myevent)/{{primaryKeyColumn}}

For instance if we continue using the example from above, the following Endpoint would target an "uppercase" event on the "customers" table:

customers(uppercase)/{{item/customerId}}

To set this up, do the following:

• Add an uppercase event to the Vinyl table
• Now set up the REST consuming side...
• Navigate to IDE > Data Servers > Your REST Data Server > Details

• Click + Endpoint on the Endpoints panel and configure the following information

  • Name: customers (uppercase)
  • Endpoint: customers(uppercase)/{{item/customerId}}
  • Method: POST

  • Sample Input - Vinyl expects the input to be in the following format:

    {
      "item": {
        "customerId": "abcde"
      }
    }
    

• Click Save

• Click Discover
• Select your customers (uppercase) endpoint
• Double click the customers (uppercase) table
• Set the customerId column as the Primary Key
• Verify the output column directions and storage types are as expected.

Create Custom Event CRUD Rule¶

In order to call the Custom Event endpoint from your REST Object, you need to create a rule which Inserts into the Endpoint.

• Navigate to App Workbench > Data Sources > Select Your REST Data Source > Logic
• Select the customer (uppercase) Endpoint
• Click + Rule in the Rules panel and set the following
  • Name: Customer (uppercase) Insert
  • Purpose: CRUD
  • Action: Insert
  • Source/Target Data Source: Your data source
  • Target: customers (uppercase)
• Click Save
• From the Tables tab:
  • Select the customerId column and set the corresponding item/customerId as the target column

Create Uppercase Event on REST Object¶

Now to hook it all up, we want to create the Uppercase event on the REST Object.

• Navigate to App Workbench > Data Sources > Select Your REST Data Source > Logic
• Click the Events icon for your REST Object
• On the Events panel, click + Table Event
• Set the Name to Uppercase
• Click Save
• On the Actions panel, click Register Existing
• Select the Customers (uppercase) Insert Rule
• Click Save
• Insert explicit bindings for customerId to customerId
• Go back to the Events page
• Double click the Uppercase event
• Set the Refresh scope to Row

You should be all set to call the custom event. To test, you can create a page with a Multi-Row Panel that has a button to call the event.

Sorting, Paging, and Filtering - Usage Type¶

The following sections on Sorting, Paging, and Filtering describe setting Usage Type on specific Parameters. The examples given are the Parameter names Vinyl uses when you access Vinyl via a REST API interface. If you are accessing other external REST API server endpoints, they will have their own unique list of Parameter names and value formats for Sorting, Paging, and Filtering. Information presented in these sections is to help you understand what each of the Usage Types are and how to use them regardless of the Parameter name used by the REST API you are accessing. The Vinyl API parameters used in these sections are further documented in the REST API article.

Sorting¶

The Usage Type that deals with sorting is Request Sort.

• Request Sort - Set this usage type on the REST parameter that the API uses for sorting. The name and content of this parameter will be defined by the API provider. For this example we use the Vinyl API parameter name of $sort.

To enable sorting (with a Vinyl REST server):¶

• Navigate to IDE > Data Servers
• Select your REST data source
• Click Details
• Under Web Service Parameters click + Parameter
• Set Type to Query
• Set Name to $sort
• Leave Value blank
• Set Usage Type to Request Sort
• Click check mark icon to save

You should now be able to sort any data that is fetched using this Vinyl REST data source.

Paging¶

The Usage Types that deal with paging are Request Count, Request Limit, Request Offset, Request Page Number, and Response Total Rows.

• Request Count - Set this Usage Type on the REST parameter that the API uses to signify that you would like a total row count returned. Some APIs do not automatically return a total count in their response and require a specific parameter as a trigger. For this example we use the Vinyl API parameter name of $count.
• Request Limit - Set this Usage Type on the REST parameter that the API uses to signify that you would like a total row count returned. Some APIs do not automatically return a total count in their response and require a specific parameter as a trigger. For this example we use the Vinyl API parameter name of $limit.
• Request Offset - Set this Usage Type on the REST parameter that the API uses to signify at what row you would like to start returning data. For this example we use the Vinyl API parameter name of $offset.
• Request Page Number - Set this Usage Type on the REST parameter that the API uses to signify at what page you would like to start returning data. Some APIs use Page Number instead of Offset, or may offer both. You should define just one for your endpoint, not both. The Vinyl API does not define a parameter for page number.
• Response Total Rows - Set this Usage Type on the REST parameter that the API uses to return a total row count in the response. Some APIs do not automatically return a total count in their response and require a specific parameter as a trigger. See the Request Count usage type above.

To enable paging (with a Vinyl REST server):¶

• Navigate to IDE > Data Servers
• Select your REST data source
• Click Details
• Under Web Service Parameters click + Parameter
  • Set Type to Query
  • Set Name to $count
  • Set Value to true
  • Set Usage Type to Request Count
  • Click checkmark icon to save
• Under Web Service Parameters click + Parameter
  • Set Type to Query
  • Set Name to $limit
  • Leave Value blank
  • Set Usage Type to Request Limit
  • Click checkmark icon to save
• Under Web Service Parameters click + Parameter
  • Set Type to Query
  • Set Name to $offset
  • Leave Value blank
  • Set Usage Type to Request Offset
  • Click checkmark icon to save
• For all Endpoints that support paging, navigate to the Endpoint table that contains the "count" parameter.
  • In our example above, this would be the customers (get) table
  • Set the count column's usage type to Response Total Rows

The Load More Rows button should now work for any data fetched from this Endpoint.

Panel Display Options¶

When you configure a panel to display REST Object data, there are options available in Edge Case that provide control over how the panel displays the records. You can control whether Vinyl loads a set number of records along with a Load More Rows button, or if it displays a set number of records along with paging navigation controls in the toolbar region to load more records.

In addition, if the REST API configuration supports it, you can set the number of records Vinyl initially displays on the panel.

To Load More Rows¶

• Navigate to the panel using the REST Object as Source
• Go to Design This Page
• Go to More > Edge Case for the panel
• Set the Paging Option to Load More Rows

To enable Paging¶

• Navigate to the panel using the REST Object as Source
• Go to Design This Page
• Go to More > Edge Case for the panel
• Set the Paging Option to Paging

To Set the Number of Initial Records Loaded¶

• Navigate to the panel using the REST Object as Source
• Go to Design This Page
• Go to More > Edge Case for the panel
• Set Rows Per Request to the numeric value you want to initially load

Filtering¶

The Usage Types that deals with filtering are Request Filter and Request Filter (OData). Set this usage type on the REST parameter that the API uses for filtering. Request Filter is for simple filtering where Request Filter (OData) is for filtering using the OData standard. This standard defines different filter conditions. The Vinyl API uses OData style filter as used in our example. Check your specific API docs to see if OData filtering is supported before using it. More information about OData filtering can be found here in this REST API Recommendations article.

To enable filtering (with a Vinyl REST server):¶

• Navigate to IDE > Data Servers
• Select your REST data source
• Click Details
• Under Web Service Parameters click + Parameter
  • Set Type to Query
  • Set Name to $filter
  • Leave Value blank
  • Set Usage Type to Request Filter (OData)
  • Click checkmark icon to save

You should now be able to filter any data that is fetched using this Vinyl REST data source.

Filtering via a REST Service supports the following:

Operators

• eq – Equal
• neq – Not equal
• gt – Greater Than
• ge – Greater Than or Equal
• lt – Less Than
• le – Less Than or Equal

Limitations

• No arithmetic operators
• No or/not logical operators
• No grouping operators
• No query functions
• No parameter aliases