Skip to Content

Complex REST API structures


New in VInyl 2.6, Vinyl's REST API now supports complex REST API structures for GET operations. With this enhancement, it is now possible to request data from multiple tables and nest the results into a single returned JSON structure.


Other HTTP methods suchs as POST and PUT are currently not supported.


  • Navigate to Vinyl IDE > Extend Your Enterprise > Publish
  • Create your REST endpoint as per usual with your root table/endpoint
  • Click on the Structure icon for your endpoint
  • Add child resources as required

Resource parameters

Name Description
Parent The parent table in the hierarchy.
Name The name of this node in the tree structure. Note that the name can include forward slashes to nest the structure even deeper.
Table The table to retrieve data from.
Field Type The type of field.
  • Array of objects: This is the default type where each row in the table is a JSON object.
  • Array of scalars: An array of single value items, serialized to a JSON array of scalars. The table must contain Index and Value columns.
  • Object: Maps to a single JSON object (effectively eliminating the JSON array). The table should only return one row at most.
Expand By Default If true, the table is expanded by default (shown in the output JSON). If false, the REST caller will need to supply an $expand=true query string property to see the data
Note that this property only impacts a collection request (e.g. /orders). A request for a specific item in a collection (e.g. /orders/101) will always expand child tables.
Get Max Limit If provided, indicates the max limit of items that can be returned in a GET request. If NULL, the default max value for the REST API is used.
Resource Bindings Sets up the bindings between the parent and child tables.

Changes to query parameters

The following query parameters have been modified to work with complex REST API structures:

  • $fields allows you to specify child tables
    • E.g. details/*: All fields of the details child table
    • E.g. details/name: Just the name field of the details child table
    • E.g. *: All fields in all tables
  • $expand a true/false parameter added to allow the REST caller to expand tables that are not expanded by default (or vice versa). Only used for collection requests.
    • E.g. $expand=true