Build your HTTP connector schema

Kathyana Queeman

Updated October 30, 2024 18:01

This article covers the schemas used to build your HTTP connector using the provided Postman collection. There are three schemas which must be used in the presented order. Learn more about the concepts behind creating an HTTP connector.

Warning

You cannot create a new resource or endpoint without a connector! You must create the connector, then the resource, and finally the endpoints. After, you can add as many resources or endpoints as you want.

Click on the POST call for each schema in Postman to get copies of the request bodies. Remember to remove the examples and connection IDs!

httpconnectors
httpconnectorresources
httpconnectorendpoints

Tip

You're simply using existing connector options in the Celigo platform to build the connector. If you're unsure what a field is used for, learn more about Custom forms and common form fields. Note that the list of common form fields is not conclusive. It simply lists the most common fields.

httpconnectors

This schema allows you to create an HTTP connector.

{
  "tempId": "toasttab_tempId",
  "name": "Toast 1",
  "published": false,
  "helpURL": "https://docs.celigo.com/hc/en-us/articles/25126630529947-Set-up-a-connection-to-Toast",
  "baseURIs": [
    "https://{{{connection.settings.domain}}}"
  ],
  "disableAutoLinking": true,
  "versioning": {},
  "versions": [
    {
      "tempId": "toasttab_version_tempId",
      "name": "1.0",
      "baseURIs": [],
      "published": true
    }
  ],
  "apis": [],
  "supportedBy": {
    "export": {
      "preConfiguredFields": [
        {
          "path": "successMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "errorMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "requestMediaType",
          "values": [
            "json"
          ]
        },
        {
            "path": "headers",
            "values": [
                [
                    {
                        "name": "Toast-Restaurant-External-ID",
                        "value": "{{{connection.settings.toastRestaurantExternalID}}}"
                    }
                ]
            ]
        }
      ]
    },
    "import": {
      "preConfiguredFields": [
        {
          "path": "successMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "errorMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "requestMediaType",
          "values": [
            "json"
          ]
        },
        {
            "path": "headers",
            "values": [
                [
                    {
                        "name": "Toast-Restaurant-External-ID",
                        "value": "{{{connection.settings.toastRestaurantExternalID}}}"
                    }
                ]
            ]
        }
      ]
    },
    "connection": {
      "preConfiguredFields": [
        {
          "path": "type",
          "values": [
            "http"
          ]
        },
        {
          "path": "http.mediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "http.ping.relativeURI",
          "values": [
            "/authentication/v1/authentication/login"
          ]
        },
        {
          "path": "http.ping.method",
          "values": [
            "POST"
          ]
        },
        {
          "path": "http.ping.body",
          "values": [
            "{\n  \"clientId\": \"{{{connection.http.unencrypted.client_id}}}\",\n  \"clientSecret\": \"{{{connection.http.encrypted.client_secret}}}\",\n  \"userAccessType\": \"TOAST_MACHINE_CLIENT\"\n}"
          ]
        },
        {
          "path": "http.headers",
          "values": [
            [
              {
                "name": "content-type",
                "value": "application/json"
              },
              {
                "name": "Toast-Restaurant-External-ID",
                "value": "{{{connection.settings.toastRestaurantExternalID}}}"
              }
            ]
          ]
        },
        {
          "path": "http.auth.type",
          "values": ["token"]
        },
        {
          "path": "http.auth.token.token",
          "values": ["x"]
        },
        {
          "path": "http.auth.token.location",
          "values": ["header"]
        },
        {
          "path": "http.auth.token.headerName",
          "values": ["Authorization"]
        },
        {
          "path": "http.auth.token.scheme",
          "values": ["Bearer"]
        },
        {
          "path": "configureTokenRefresh",
          "values": [true]
        },
        {
          "path": "http.auth.token.refreshMethod",
          "values": ["POST"]
        },
        {
          "path": "http.auth.token.refreshRelativeURI",
          "values": [
            "https://{{{connection.settings.domain}}}/authentication/v1/authentication/login"
          ]
        },
        {
          "path": "http.auth.token.refreshBody",
          "values": [
            "{\n  \"clientId\": \"{{{connection.http.unencrypted.client_id}}}\",\n  \"clientSecret\": \"{{{connection.http.encrypted.client_secret}}}\",\n  \"userAccessType\": \"TOAST_MACHINE_CLIENT\"\n}"
          ]
        },
        {
          "path": "http.auth.token.refreshTokenPath",
          "values": ["token.accessToken"]
        },
        {
          "path": "http.auth.token.refreshTokenLocation",
          "values": ["body"]
        },
        {
          "path": "http.auth.token.refreshToken",
          "values": ["x"]
        },
        {
          "path": "http.encryptedFields",
          "values": [
            {
              "id": "client_secret",
              "name": "client_secret",
              "type": "text",
              "inputType": "client_secret",
              "label": "Client secret",
              "description": "Note: for security reasons this field must always be re-entered.",
              "required": true,
              "helpText": ""
            }
          ]
        },
        {
          "path": "http.unencryptedFields",
          "values": [
            {
              "id": "client_id",
              "name": "client_id",
              "type": "text",
              "label": "Client ID",
              "required": true,
              "helpText": "Enter your Bloomfire account email ID."
            }
          ]
        },
        {
          "path": "settingsForm",
          "values": [
            {
              "fieldMap": {
                "domain": {
                  "id": "domain",
                  "name": "domain",
                  "type": "text",
                  "label": "Domain",
                  "required": true,
                  "displayAfter": "connection.application",
                  "helpText": "Enter your Toast account domain. For example, if your account URL is https://test.toasttab.com, then test.toasttab.com is the domain."
                },
                "toastRestaurantExternalID": {
                  "id": "toastRestaurantExternalID",
                  "name": "toastRestaurantExternalID",
                  "type": "text",
                  "label": "Toast restaurant external ID",
                  "required": true,
                  "displayAfter": "connection.settings.domain",
                  "helpText": "Enter your Toast restaurant external ID provided by the Toast <a href='https://central.toasttab.com/s/contact-support'>support</a> team."
                }
              },
              "layout": {
                "fields": [
                  "domain",
                  "toastRestaurantExternalID"
                ]
              }
            }
          ]
        }
      ],
      "fieldsUserMustSet": [
        {
          "path": "settings.domain"
        },
        {
          "path": "settings.toastRestaurantExternalID"
        },
        {
          "path": "http.unencrypted.client_id"
        },
        {
          "path": "http.encrypted.client_secret"
        }
      ]
    }
  }
}

Request body

The request body is as follows:

Key	Definition
`Name` (required)	Name of the application.
`Published` (required)	This field must always remain false.
`baseURIs` (required)	The application's base URL. It's an array object field that can hold multiple base URIs, but by default, it will show the very first URI from the array. It can be mentioned globally, locally, and inside the version array object.
`helpURL`:	Add a link to your own connection guide.
`Versioning`:	Defines how the versioning is done for this application. See the versioning subSchema for more.
`Versions`(required)	An array of different versions applicable for the connector/api. The version is explained in the Versions subSchema.
`apis`	If the connector has multiple independent APIs, a list of all APIs should be defined. This should be an array. For example, Shopify has Partner APIs and Payment APIs. Both are mutually exclusive APIs designed for different purposes. See the APIs subSchema for more.
`supportedBy` (required)	Configurations and settings applicable for this connector. See the supportedBy subSchema for more.

versioning subSchema

{
       location: [uri, query_parameter, header]
       headerName: ''
       queryParameterName: ''
}

Key	Definition
`location`	Determines where your versioning will be mentioned: `uri`, `query_parameter`, `header`.
`headerName`	If the version is not mentioned in the URI, it can be in the header, but you must provide a header name.
`queryParameterName`	If the version is not mentioned in the URI or header, it can be a query parameter, but you must provide a query parameter name.

versions subSchema

 "versions": [
    {
      "tempId": "toasttab_version_tempId",
      "name": "1.0",
      "baseURIs": [],
      "published": true
    }
  ],

Key	Definition
`baseURIs`	The application's base URL is an array object field that can hold multiple base URIs, but by default, it will show the very first URI from the array. It can also be mentioned globally and locally inside the version array object as a requirement.
`relativeURI`	Relative to your connector’s version.

APIs subSchema

Key	Definition
`name` (required)	API name
`published`	This field must always remain `false`.
`versioning`	versioning SubSchema
`Versions` (required)	versions SubSchema

supportedBy subSchema

For Export and Import subschemas:

"supportedBy": {
    "export": {
      "preConfiguredFields": [
        {
          "path": "successMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "errorMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "requestMediaType",
          "values": [
            "json"
          ]
        },
        {
            "path": "headers",
            "values": [
                [
                    {
                        "name": "Toast-Restaurant-External-ID",
                        "value": "{{{connection.settings.toastRestaurantExternalID}}}"                    }
                ]
            ]
        }
      ]
    },

"supportedBy": {
    "import": {
      "preConfiguredFields": [
        {
          "path": "successMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "errorMediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "requestMediaType",
          "values": [
            "json"
          ]
        },
        {
            "path": "headers",
            "values": [
                [
                    {
                        "name": "Toast-Restaurant-External-ID",
                        "value": "{{{connection.settings.toastRestaurantExternalID}}}"
                    }
                ]
            ]
        }    
    ]
},

Key	Definition
`preConfiguredFields` (required)	Requirements that remain the same regardless of who created the connection or when it was created. For example, the application’s Base URI (if fixed) or the authentication type. Learn more about preConfiguredFields.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.
`fieldsUserMustSet` (Required)	Fields under this array object are mandatory, and users must provide input. Learn more about fieldsUserMustSet.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.

For Connection subschemas:

"connection": {
      "preConfiguredFields": [
        {
          "path": "type",
          "values": [
            "http"
          ]
        },
        {
          "path": "http.mediaType",
          "values": [
            "json"
          ]
        },
        {
          "path": "http.ping.relativeURI",
          "values": [
            "/authentication/v1/authentication/login"
          ]
        },
        {
          "path": "http.ping.method",
          "values": [
            "POST"
          ]
        },
        {
          "path": "http.ping.body",
          "values": [
            "{\n  \"clientId\": \"{{{connection.http.unencrypted.client_id}}}\",\n  \"clientSecret\": \"{{{connection.http.encrypted.client_secret}}}\",\n  \"userAccessType\": \"TOAST_MACHINE_CLIENT\"\n}"
          ]
        },
        {
          "path": "http.headers",
          "values": [
            [
              {
                "name": "content-type",
                "value": "application/json"
              },
              {
                "name": "Toast-Restaurant-External-ID",
                "value": "{{{connection.settings.toastRestaurantExternalID}}}"
              }
            ]
          ]
        },
        {
          "path": "http.auth.type",
          "values": ["token"]
        },
        {
          "path": "http.auth.token.token",
          "values": ["x"]
        },
        {
          "path": "http.auth.token.location",
          "values": ["header"]
        },
        {
          "path": "http.auth.token.headerName",
          "values": ["Authorization"]
        },
        {
          "path": "http.auth.token.scheme",
          "values": ["Bearer"]
        },
        {
          "path": "configureTokenRefresh",
          "values": [true]
        },
        {
          "path": "http.auth.token.refreshMethod",
          "values": ["POST"]
        },
        {
          "path": "http.auth.token.refreshRelativeURI",
          "values": [
            "https://{{{connection.settings.domain}}}/authentication/v1/authentication/login"
          ]
        },
        {
          "path": "http.auth.token.refreshBody",
          "values": [
            "{\n  \"clientId\": \"{{{connection.http.unencrypted.client_id}}}\",\n  \"clientSecret\": \"{{{connection.http.encrypted.client_secret}}}\",\n  \"userAccessType\": \"TOAST_MACHINE_CLIENT\"\n}"
          ]
        },
        {
          "path": "http.auth.token.refreshTokenPath",
          "values": ["token.accessToken"]
        },
        {
          "path": "http.auth.token.refreshTokenLocation",
          "values": ["body"]
        },
        {
          "path": "http.auth.token.refreshToken",
          "values": ["x"]
        },
        {
          "path": "http.encryptedFields",
          "values": [
            {
              "id": "client_secret",
              "name": "client_secret",
              "type": "text",
              "inputType": "client_secret",
              "label": "Client secret",
              "description": "Note: for security reasons this field must always be re-entered.",
              "required": true,
              "helpText": ""
            }
          ]
        },
        {
          "path": "http.unencryptedFields",
          "values": [
            {
              "id": "client_id",
              "name": "client_id",
              "type": "text",
              "label": "Client ID",
              "required": true,
              "helpText": "Enter your Bloomfire account email ID."
            }
          ]
        },
        {
          "path": "settingsForm",
          "values": [
            {
              "fieldMap": {
                "domain": {
                  "id": "domain",
                  "name": "domain",
                  "type": "text",
                  "label": "Domain",
                  "required": true,
                  "displayAfter": "connection.application",
                  "helpText": "Enter your Toast account domain. For example, if your account URL is https://test.toasttab.com, then test.toasttab.com is the domain."
                },
                "toastRestaurantExternalID": {
                  "id": "toastRestaurantExternalID",
                  "name": "toastRestaurantExternalID",
                  "type": "text",
                  "label": "Toast restaurant external ID",
                  "required": true,
                  "displayAfter": "connection.settings.domain",
                  "helpText": "Enter your Toast restaurant external ID provided by the Toast <a href='https://central.toasttab.com/s/contact-support'>support</a> team."
                }
              },
              "layout": {
                "fields": [
                  "domain",
                  "toastRestaurantExternalID"
                ]
              }
            }
          ]
        }
      ],
      "fieldsUserMustSet": [
        {
          "path": "settings.domain"
        },
        {
          "path": "settings.toastRestaurantExternalID"
        },
        {
          "path": "http.unencrypted.client_id"
        },
        {
          "path": "http.encrypted.client_secret"
        }
      ]
    }
  }
}

Key	Definition
`preConfiguredFields` (required)	Requirements that remain the same regardless of who created the connection or when it was created. For example, the application’s Base URI (if fixed) or the authentication type. Learn more about preConfiguredFields.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.
`fieldMap`
`Name` (Required)
`Type` (Required)
`Label`
`Required`
`helpText`
`fieldsUserMustSet` (required)	Fields under this array object are mandatory, and users must provide input. Learn more about fieldsUserMustSet.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.

httpconnectorresources

This schema allows you to create an HTTP resource.

{
    "tempId": "audit_trail",
    "name": "AuditTrail",
    "published": true,
    "_httpConnectorId": "664e075a780d6ecff6f196eb",
    "_versionIds": ["664e075a780d6ecff6f196ec"],
    "resourceFields": [
      {
        "id": "text",
        "dataType": "string"
      },
      {
        "id": "objects",
        "dataType": "objectarray",
        "resourceFields": [
          {
            "id": "type",
            "dataType": "string"
          },
          {
            "id": "ids",
            "dataType": "stringarray"
          }
        ]
      }
    ]
  }

Resource body

Key	Definition
`_id` (required)	A unique identifier for each resource, later used to render the endpoints under respective resources.
`name` (required)	Name of the resource.
`published`	This field must always remain false.
`_versionId` (required)	An array field that will provide the version IDs generated after making the `httpconnectors` API call. Based on the provided version IDs and connector ID, this resource will render for a particular connector.
`_httpConnectorId` (required)	Unique connector ID from the `httpconnectors` API response after making the API call. Note The `_versionId` and `_httpConnectorId` are only available after creating the connector using the `httpconnectors` API endpoint. You’ll need to copy these values from the `httpconnectors` API response body after creating the connector.
`resourceFields`	This is an array object field, which will be used to define the structure of the request body for a resource as per the API Doc or to produce the mapping dropdown.
`id`	Unique identifier of the resource field.
`dataType`	Defines the datatype (Object, ArrayObject, String, etc.).
`resourceFields`	Supported resource fields.
`id`	Unique identifier of the resource field.
`dataType`	Defines the datatype (Object, ArrayObject, String, etc.).

httpconnectorendpoints

This schema allows you to create an HTTP endpoint.

{
    "tempId": "get_api_members_system_api_members_get",
    "name": "Get API members",
    "description": "",
    "published": true,
    "_httpConnectorResourceIds": [
      "6540a7540081a9eca616dd54"
    ],
    "method": "GET",
    "relativeURI": "/system/apiMembers?page={{export.http.paging.page}}",
    "queryParameters": [
      {
        "name": "conditions",
        "description": "conditions",
        "required": false,
        "dataType": "input",
        "label": "conditions"
      },
      {
        "name": "orderBy",
        "description": "orderBy",
        "required": false,
        "dataType": "input",
        "label": "orderBy"
      },
      {
        "name": "childconditions",
        "description": "childconditions",
        "required": false,
        "dataType": "input",
        "label": "childconditions"
      },
      {
        "name": "customfieldconditions",
        "description": "customfieldconditions",
        "required": false,
        "dataType": "input",
        "label": "customfieldconditions"
      },
      {
        "name": "page",
        "description": "page",
        "required": false,
        "dataType": "number",
        "label": "page"
      },
      {
        "name": "pageSize",
        "description": "pageSize",
        "required": false,
        "dataType": "number",
        "label": "pageSize"
      },
      {
        "name": "pageId",
        "description": "pageId",
        "required": false,
        "dataType": "number",
        "label": "pageId"
      }
    ],
    "pathParameters": [],
    "supportedBy": {
      "type": "export",
      "preConfiguredFields": [],
      "fieldsUserMustSet": [],
      "fieldsToUnset": [],
      "lookupToIdentifyExisting": {}
    }
  }

Request body

Key	Definition
`name` (required)	Endpoint name.
`description`	Description of the endpoint.
`published`	This field must always remain `false`.
`_httpConnectorResourceId`	Unique resource ID from the httpconnectorresources API response after making the API call. Note The `_httpConnectorId` is only available after creating the connector using the `httpconnectors` API endpoint. Similarly, the `_httpConnectorResourceId` is only available after creating the resource using the `httpconnectorresources` API endpoint. You’ll need to copy these values from the API response bodies after creating them.
`method` (required)	Method of the endpoint.
`relativeURI` (required)	Relative URL of the endpoint.

pathParameters subSchema

Key	Definition
`queryParameters`	All query parameters can be defined under this array object.
`name` (required)	Name of the query parameter.
`description` (required)	Description of the query parameter.
`required` (required)	A boolean field that defines if the resource is required.

supportedBy endpoint subSchema

For Export subschemas:

Key	Definition
`preConfiguredFields`	Requirements that remain the same regardless of who created the connection or when it was created. For example, the application’s Base URI (if fixed) or the authentication type. Learn more about preConfiguredFields.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.
`resourcePath`
`fieldsToUnset`
`lookupToIdentifyExisting`
`fieldsUserMustSet`	Fields under this array object are mandatory, and users must provide input. Learn more about fieldsUserMustSet.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.

For Import subschemas:

Key	Definition
`preConfiguredFields`	Requirements that remain the same regardless of who created the connection or when it was created. For example, the application’s Base URI (if fixed) or the authentication type. Learn more about preConfiguredFields.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.
`Name`
`Value`
`fieldsToUnset`
`lookupToIdentifyExisting`
`pathParameterToIdentifyExisting`
`fieldsUserMustSet`	Fields under this array object are mandatory, and users must provide input. Learn more about fieldsUserMustSet.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.

For Connection subschemas:

Key	Definition
`preConfiguredFields`	Requirements that remain the same regardless of who created the connection or when it was created. For example, the application’s Base URI (if fixed) or the authentication type. Learn more about preConfiguredFields.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.
`fieldsUserMustSet`	Fields under this array object are mandatory, and users must provide input. Learn more about fieldsUserMustSet.
`path`	Each path will be used to provide a location that we want to pre-configure.
`values`	Each value will contain one or more details that you want to predefine for a specific location or field. By providing a path, the value can be assigned to any particular location or field.