Skip to Content

REST Data Source

Overview

The REST Data Source provides developers with the ability to connect Vinyl to various REST servers, including other instances of Vinyl. Setting up a REST Data Source involves three basic steps:

  1. Creating and configuring the REST Data Source server
  2. Creating REST endpoints for each API method you will be calling
  3. For REST CRUD-style APIs, optionally creating a REST super object

REST Data Source Server

The REST Data Source Server configuration contains information that is used across all REST endpoints.

Create the REST Data Server

  • Navigate to IDE > Data Servers
  • Click + Server
  • Enter a Server Name
  • Select Type REST API under Web Services

  • Enter the URL of the server to connect to

    Note

    Endpoints you configure in the next section will append to this main URL. If we assume a REST server endpoint of https://api.google.com/rest/v1/analytics the configuration could look like:

    Server URL: https://api.google.com/rest/v1 Endpoint: analytics

  • Enter the request and response content type. Typically REST servers communicate via JSON

  • Enter Security Settings, if required
    • Most REST APIs use an API key in the header which we configure in a later section
  • Click Save and close the dialog

You should see your REST Data Server in the list of Data Servers.

Configure Request Headers

Most REST services require you to pass in an API key using the request header. Configure the request header as follows:

  • Navigate to IDE > Data Servers
  • Click the Details button for the Data Server you configured
  • In the Web Service Parameters panel, click + Parameter
    • Select Header as the Type
    • Add the Name of the header parameter
      • E.g. for Vinyl REST servers the api key is passed using "X-API-Key"
  • Add the Value of the header parameter
  • Click the checkmark icon to save

Configure Query String Parameters

If you have common query string parameters to use across end points you can configure them as follows:

  • Navigate to IDE > Data Servers
  • Click the Details button for the Data Server you configured
  • In the Web Service Parameters panel, click + Parameter
    • Select Query as the Type
    • Add the Name of the query string parameter
    • Add the Value of the query string parameter
  • Click the checkmark icon to save

REST Endpoints

Once your REST Data Server has been configured, you can add API endpoints.

Add an Endpoint

  • Navigate to IDE > Data Servers
  • Click the Details button for the Data Server you configured
  • In the Endpoints panel, click + Endpoint
    • Enter the Name of the Endpoint
    • Enter the Endpoint. This value is appended to the REST Data Server URL
      • E.g. If our REST Data Server URL is set to https://api.google.com/rest/v1, an endpoint of "analytics" will result in the following URL: https://api.google.com/rest/v1/analytics
  • Select the HTTP Method for the endpoint
  • If you want to override the endpoint Response or Request content type, click More and select Edge Case
    • From the Content Type section there are two fields available for this configuration:
      • Request: Selected value will override the server Request content type
      • Response: Selected value will override the server Response content type
    • The default value for Request and Response is not set, and will be inherited from the server content type. Content Type values include File, JSON, Multipart, Plain Text, and XML.
  • Click Save
  • Click Discover to review the proposed query, and click Discover again to execute the query
    • This will generate input parameters for any Sample Input entered
    • As well, output tables will be generated for any data coming back from the endpoint
  • Click Test Connection and then Proceed to call the endpoint. If input parameters are defined, their test value will be sent.

Resources