Connectors

Learn about defining and using Connectors, which wrap third party REST APIs.

Connectors provide a secure and type-safe way to access third party REST APIs. Defining a connector requires only a simple file/folder layout that closely maps to the third party's REST structure. Each connector uses a dedicated GIT repository.

Before defining a new connector, double check that one doesn't already exist in our registry. If you develop a new connector, get in touch ‐ we'd love to consider including it in the public registry.

Manifest

In the root directory, define a manifest file: /🎛.yaml

Example


name: site24x7.com

type: rest-api

rest-api:
  prefix: https://www.site24x7.com/api
  docs: https://www.site24x7.com/help/api/
  token: Zoho-authtoken
  payload: json
  accept: application/json; version=2.0
        

name

Typically the domain name the connector is for. This name is used for credential keys, and once in production use the name should never change. Using the domain also ensures uniqueness.

prefix

The prefix will be prepended to all endpoint paths for this connector.

token

The name of the token expected in the Authorization header.

payload

Either json or form, to indicate how request content should be encoded and passed to non-GET endpoints.

accept

The Accept header expected by the third party API.

Definition

The definition of a connector involves mapping folders/files to third party REST endpoints.

Example


/balance/history/{txn}/get.yaml

REST endpoint result:

GET /balance/history/{txn}

JavaScript use:

balance.history('txn').get()
        

POST Example


/customers/{customer}/update.yaml

REST endpoint result:

POST /customers/{customer}

JavaScript use:

customers('customer').update({ payload });
        

Within the update.yaml file specify method: POST

Importing

Connectors must be imported into the project that will use it. Define a file in the root named /🔌.yaml Within this file specify each imported connector's GIT source (branch is optional):


- https://github.com/stacklane-registry/site24x7.com.git#branch-or-tag
        

Credentials

Most third party APIs require an authorization token. To pass the authorization token during development builds, see the development credentials JSON format.

The credential key for a connector is api:[connector-name], where [connector-name] is the name of rest API's root domain.