REST Connector Configuration Guide – Skyvia

REST Connection Configuration Guide

When working with custom REST connectors, metadata plays a crucial role in defining the structure of your API connection. It helps the system understand how to interact with the endpoints, what data is expected, and how to communicate with the API. This information is essential for correct API calls, error handling, and ensuring that your connector functions as intended.




We are attaching two files with metadata examples:
  1. Basic metadata example 
  2. Advanced metadata example

Basic Overview

The metadata for a REST connection must follow this format:
{
  "ProviderConfiguration": { ... },
  "Metadata": [ ... ]
}

ProviderConfiguration

Contains connection settings such as headers. In some cases, this block may be left empty.

Metadata

Describes specific API endpoints, including:

  • URL

  • List of columns with data types

  • Supported methods (GET, POST, etc.)

Headers Example

{
  "ProviderConfiguration": {
    "Headers": [
      { "Key": "X-API-Version", "Value": 2 }
    ]
  } }


For multiple headers:

"Headers": [
  { "Key": "X-API-Version", "Value": 2 },
  { "Key": "Authorization", "Value": "Bearer 1254fhr545fr" }
]


For general instructions, refer to the REST connector documentation. The examples above provide a simple overview.

Advanced Configuration

The advanced example extends the basic configuration with additional settings.


ProviderConfiguration


AuthenticationToken Example for OAuth 2.0 authentication.
  • PagingStrategy Default type: LimitOffset.
    • If not defined at the object level, the default strategy applies.
    • Objects can override with their own paging type.
  • DateTimeFormat Default: "yyyy-MM-ddTHH:mm:ssZ".
    • Specify if the API returns DateTime in another format.
    • Can be set globally or at the column level.
  • DateFormat Default: "yyyy-MM-dd".
    • Specify if the API uses another format for Date values.
    • Can be set globally or at the column level.
  • ConstantParameters Array of parameters with fixed values.
    Example:
    "Url": "/accounts?organization=WO0qRGel5fKZMnMSvDNKofmq4"
  • SortOperation Example type: JoinColumnAndDirection. Used when the API requires one parameter containing “column name + sort direction”. Example: /deals?sort=person_id asc,updated_date desc

Procedures

Defined in the Procedures block. Example: GetTransactions

  • Required parameter: view

  • Optional parameters: startdate, enddate

Usage:

call GetTransactions(:view)
call GetTransactions(:view, :startdate, :enddate)

Object-Level Examples that are described in the Advanced Metadata File

Accounts object

  • PagingStrategy = WithoutPaging → single request.

  • SortOperation → requires two parameters: sort_field and sort_direction. Example: /deals?sort_field=id&sort_direction=asc

  • BodyPattern → Indicates the format of the body payload for Insert/Update operations. The default value is a JSON object (not specified in the settings).

    • Example override:

      "{ \"data\": [ <$body$> ] }"

  • Columns

    • Id: "Primary": true → Primary Key

    • Name: "Required": true → mandatory on Insert

    • DMLAPIName: "account.name" → used when body field name differs from APIPath

    • CreatedDate: "TimeStampStoreMode": "SecondsSinceEpoch"

    • UpdatedDate: "TimeStampStoreMode": "MillisecondsSinceEpoch"

  • InsertOperation / UpdateOperation

    • Default: InputType = JSONBody as described for INSERT operation

    • Example override: We form and send the body as a JSON object. But sometimes an API requires the body for Insert/Update operations to be sent in a different format. In this metadata example, the InputType for UpdateOperation is set to “RestParameters,” which means that the body will be sent as a set of URL parameters.


Contacts object

  • PagingStrategy = PageNo → parameter names must match API documentation.

  • CreatedDate column

    • Includes FilterOperations supporting >, >=, <, <=.

    • Native filter parameters (e.g., filters[created_before], filters[created_after]) come from your API docs.

    • Delta allows shifting by ±1 second to extend operator coverage (for example, if the API has a parameter filters[created_before] that corresponds to our LessThan operator, then with Delta:1, the filter with the LessThanOrEquals operator will also work natively).

  • InsertOperation / UpdateOperation

    • InputType = UrlencodedBody → body sent as key–value pairs. This means that the body is sent as key–value pairs, where the 'Key' is the parameter name and the 'Value' is its corresponding value.

Notes

  • Always review the REST connector documentation first. It describes all standard configurations and provides examples.

  • The metadata examples attached here illustrate possible metadata configurations.

  • Each API is different, metadata must be created according to the documentation of the specific connector.

    • Related Articles

    • Zoho CRM: Inactive User Cannot Access the API Error

      Overview This error is returned by the Zoho CRM API. Skyvia connects to data sources through their APIs and is subject to their features and limitations. Unfortunately, there are no additional details available beyond what their API returns. ...

    • Skyvia Backup Errors Caused by Salesforce API Requirements

      Overview Skyvia interacts with Salesforce via its API. During a backup or replication operation, you may encounter errors caused by certain limitations or behaviors specific to the Salesforce API. Why This Happens When Skyvia performs a backup or ...

    • Salesforce Report exports only 2000 records

      Overview When using Salesforce Reports as a data source in Skyvia, the export is limited to the first 2,000 rows. This is not a Skyvia limitation, it is a hard restriction imposed by the Salesforce Run Report API, which Skyvia uses to retrieve report ...

    • Salesforce Connect: Can't Sync Schema Metadata (Error Code: Null)

      Overview This error occurs because the object used in your endpoint does not have a primary key column. Salesforce requires a primary key for external objects, which is why you encounter an error when validating and syncing your External Data Source ...

    • A Quick Guide to Importing and Updating Audience Members in Mailchimp

      Overview This article explains how to configure an UPSERT operation for the Mailchimp ListMembers object in Skyvia. This is the recommended approach for importing and updating Audience members without creating duplicates. How UPSERT Works for ...