> ## Documentation Index
> Fetch the complete documentation index at: https://docs.versori.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Connector Versions
> ListConnectorVersions returns a page of ConnectorVersions ordered by most recently updated first. Customising
the sort behaviour is not currently supported but may be added in the future. Similarly with filtering, this
will be implemented in a future release.
## OpenAPI
````yaml get /o/{organisation_id}/connectors/{connector_id}/versions
openapi: 3.1.0
info:
title: Versori Connect API
version: 0.0.1
license:
name: UNLICENSED
identifier: UNLICENSED
description: >
Connect API allows you to connect to your external systems to the Versori
Platform.
The main component of the Connect API are Connectors. Connectors are split
into the following components:
- Protocol
- Authentication Scheme
- Connections
- Global Parameters
- Actions
- Triggers
- Definitions
## Protocol
The protocol defines the transport mechanism used to communicate with your
external system.
Currently, only HTTP/REST APIs are supported within Connect API, however our legacy "Apps" functionality is
available on [Switchboard API](/api-reference/switchboard-api) which supports GraphQL APIs and SOAP web
services.
## Authentication Scheme
The authentication scheme defines how the Versori Platform will authenticate
with your external system. Different
schemes are applicable to different protocols.
### HTTP
The following authentication schemes are supported for HTTP:
- OAuth 2.0 - OIDC - API Key (in header, query or cookie) - Basic - Bearer
## Connections
Each Connector has at least one connection and additional connections can be
added. Connections are used to connect
to different instances of your external system. For example, you may have a
development, staging and production
connection, each with different credentials and addresses. Each Connection
must provide a Credential which satisfies
one authentication scheme for the Connector. Connections can define
variables, which can be used to customise
certain aspects of the Connector such as default values for certain
fields/parameters.
Finally, some protocols may require specific configuration for each
connection. For example, the HTTP Protocol
requires a base URL for each connection.
## Global Parameters
Global Parameters allows a user to configure a set of parameters which can
be used across multiple Actions. Within
the UI, whenever a user starts to create a new Action the UI will
pre-populate the Action with the Global
Parameters. If the Action in question does not require any of these
parameters the user may delete them before
saving.
When a user creates, updates or deletes a global parameter, the user will be
prompted to choose which Actions should
reflect the change, with the ability to choose all, some or none.
### HTTP Parameters
For HTTP Connectors, the following parameter types may be set as Global
Parameters: - Path parameters - Query
parameters - Headers
## Actions
Actions define the actions that can be performed on your external system. An
action may be defined and implemented
differently depending on the protocol. For example, an HTTP Action contains
a method like GET, PUT, POST etc.,
whereas a BigQuery Actions will contain a SQL query.
### HTTP
For HTTP Connectors, each Action defines a single HTTP request.
The Action can contain inputs to customise the request, some inputs may also
allow default values which can be
overridden when used within other Versori products. Default values can be
defined using connection variables.
The supported HTTP inputs are: - Path parameters - Query parameters -
Headers - Request body Definitions (one per
supported media-type)
The Action can also define outputs: - Headers - Status Codes, and their
associated Response body Definitions (one
per supported media-type)
### BigQuery SQL
BigQuery SQL Actions are defined as SQL queries. The query can contain
parameters to customise the query at runtime,
for example in Switchboard a user may use literal values or Selectors to
provide the parameters. This functionality
is provided via the
[query](https://cloud.google.com/bigquery/docs/reference/rest/v2/jobs/query)
API endpoint.
When creating a BigQuery SQL Action, the associated Definition is
automatically created based on the query.
## Triggers
Triggers define how the Versori Platform will be notified of events from
your external system. Each Protocol
determines how Triggers are defined since how they are implemented may vary.
### HTTP Triggers
These are essentially webhooks, which an external service may invoke to
notify the Versori Platform of an event.
They are modelled similarly to HTTP Actions, but Versori expects a certain
request and allows the user to configure
the response.
In the future, you will also be able to define HTTP Trigger Lifecycles,
which define how a webhook is
created/deleted on the external system when a Switchboard integration is
published/unpublished. However, this is out
of scope for the initial release.
## Definitions
Definitions provide the Versori Platform the information required to
validate and provide auto-complete behaviour
when dealing with input/output data between connectors.
Each definition has a media-type and an associated schema. Which schema
implementation is used depends on the
media-type, we initially support the following: - `application/json`,
defined by JSON Schemas. - `text/xml`, defined
by XML Schema Definitions (XSDs). - `text/csv`, how this is defined isn't
known yet, however there are discussions
in JIRA about this.
## Versioning
Except for the top-level Connector data and their Connections, other aspects
of a Connector such as Actions,
Triggers and Definitions are versioned resources. A connector can have
multiple versions and each version can either
be in "draft" or "published" state. A version is published if its
`publishedAt` field is not null.
Versions are defined as an arbitrary string, but users are encouraged to
follow a consistent versioning scheme such
as SemVer, CalVer, or an incrementing number.
Connectors may only be used by Versori products if they are published, and
once published they are immutable. If an
edit is attempted against a published version then an error will be
returned. Unpublished Connectors are considered
to be in "draft" and can be edited as many times as required.
Connectors may be unpublished, but only when they are not referenced by any
other system (see
[Subscribers](#Subscribers) below).
### Special Versions
There are two reserved words to reference a published version, "latest" and
"default". "latest" will always return
the latest published version according to it's `publishedAt` field, whereas
"default" will return the version which
has been set as such by the user. If the user never specifies a default
version, the "latest" published version will
be used.
### Publishing Versions
When a new version is published, the user should be prompted to choose how
Versori products should handle the
update. For example, for Switchboard the user should be able to choose
whether to update existing integrations to
use the new version, or to leave them as they are. To facilitate this UX the
Connect API has the concept of
subscriptions (is there a better name?) where other APIs can register their
interest in a Connector.
## Subscribers
A Connector has the concept subscribers, where other products can notify the
Connect API of their interest in that
connector. This allows the Connect API to check whether a Connector is being
used by other products and prevent
deletion if so.
### Switchboard
When a board is published, the Switchboard orchestrator will subscribe to
the Connector. When that board is then
unpublished, the orchestrator will unsubscribe from the Connector.
## Completions
Coming Soon
Completions is an advanced feature of the Connect API which enables
Connector authors to define how a particular
field within a Definition may be auto-completed. This is useful for fields
which are almost always a fixed value but
whose valid values are determined by how the external system is configured.
i.e. the `channel` field in a Slack
`postMessage` call must be a valid channel name for the Slack Workspace in
which the Connector is connecting to.
There are different mechanisms for defining Completions which are described
below.
### Static Completions
Static Completions are defined by the Connector author and are a fixed list
of values. For JSON Definitions, this is
automatically generated by properties with the `enum` keyword. Other
media-types will have their own mechanisms
which may or may not be directly supported by their schema implementation.
### Remote Completions
Remote Completions make a connector to an external API to retrieve the valid
values for a field. Initially a
Completion can be defined by choosing another Connector Action, and a
transformation on how to extract the values to
present to the user.
servers:
- description: Production
url: https://platform.versori.com/api/connect/v1
- description: Staging
url: https://platform-staging.versori.com/api/connect/v1
- description: Development
url: http://localhost:8082
security:
- bearerToken: []
- cookie: []
tags:
- name: protocol-http
description: >
The HTTP Protocol allows the Connect API to communicate with external
systems via HTTP requests.
- name: connectors
description: >
Connectors are the core resource of the Connect API. They represent a
connector to an external system, and
contains the information required to interact with that system.
- name: connector-versions
description: >
Connector Versions belong to a Connector and maintains the set of Actions,
Triggers and Definitions for a
Connector.
- name: auth-schemes
description: >
Auth Schemes are the mechanism by which the Connect API authenticates with
external systems. They define how
Actions and Triggers are authenticated. Not all Auth Schemes are supported
by all Protocols, you can use the
[GET
/auth-schemes](/api-reference/connect-api/protocols/list-auth-schemes)
endpoint
to determine which Auth Schemes are supported for each Protocol.
- name: connections
description: |
Connections define how Actions and Triggers are authenticated.
- name: credentials
description: >
Credentials are the mechanism by which the Connect API authenticates with
external systems. They define how
Actions and Triggers are authenticated. Which Credentials are supported
depends on the Auth Scheme chosen, which
again is determined by the Protocol.
- name: actions
description: >
Actions define how the Versori Platform will interact with your external
system. Each Protocol determines how
Actions are defined since how they are implemented may vary.
- name: triggers
description: >
Triggers define how the Versori Platform may receive requests from your
external systems. Each Protocol
determines how Triggers are defined since how they are implemented may
vary.
- name: definitions
description: >
Definitions provide the Versori Platform the information required to
validate and provide auto-complete behaviour
when dealing with input/output data between connectors. Each definition
has a media-type and an associated schema
which is compatible with that media-type, for example JSON Schema is used
for `application/json` media-types.
- name: protocols
description: >
Protocols are the mechanism by which the Connect API communicates with
external systems. They define how Actions,
Triggers and Definitions are implemented.
- name: protocol-bigquery
description: >
The BigQuery Protocol allows the Connect API to communicate with BigQuery
datasets via the BigQuery API.
- name: misc
description: |
Miscellaneous endpoints which don't fit into any other category.
paths:
/o/{organisation_id}/connectors/{connector_id}/versions:
parameters:
- $ref: '#/components/parameters/organisation_id'
- $ref: '#/components/parameters/connector_id'
get:
tags:
- connector-version
summary: List Connector Versions
description: >
ListConnectorVersions returns a page of ConnectorVersions ordered by
most recently updated first. Customising
the sort behaviour is not currently supported but may be added in the
future. Similarly with filtering, this
will be implemented in a future release.
operationId: ListConnectorVersions
parameters:
- $ref: '#/components/parameters/first'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/ConnectorVersionsPage'
default:
description: Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
parameters:
organisation_id:
name: organisation_id
in: path
required: true
schema:
type: string
format: ulid
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
connector_id:
name: connector_id
in: path
required: true
description: ID is the unique identifier of the Connector.
schema:
type: string
format: ulid
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
first:
name: first
in: query
required: false
schema:
type: integer
default: 20
after:
name: after
in: query
required: false
schema:
type: string
before:
name: before
in: query
required: false
schema:
type: string
schemas:
ConnectorVersionsPage:
description: ConnectorVersionsPage is a page of ConnectorVersions.
type: object
allOf:
- $ref: '#/components/schemas/PageInfo'
- properties:
items:
type: array
items:
$ref: '#/components/schemas/ConnectorVersion'
required:
- items
Error:
type: object
properties:
code:
type: string
description: Code is a machine-readable error code.
message:
type: string
description: Message is a human-readable error message.
fields:
type: array
items:
$ref: '#/components/schemas/ErrorField'
x-go-type-skip-optional-pointer: true
details:
type: string
x-go-type-skip-optional-pointer: true
required:
- code
- message
PageInfo:
type: object
properties:
totalCount:
type: integer
next:
type: string
x-go-type-skip-optional-pointer: true
prev:
type: string
x-go-type-skip-optional-pointer: true
required:
- totalCount
ConnectorVersion:
description: ConnectorVersion represents a version of a Connector.
type: object
properties:
id:
type: string
format: ulid
description: >
ID is the unique identifier of the ConnectorVersion, this is
typically only used internally and the version
`name` is used externally in combination with the Connector `id`.
x-go-name: ID
x-go-type: ulid.ULID
x-go-type-import:
path: versori.dev/vergo/ulid
name:
type: string
description: >
Name denotes the actual version value for the Connector. This can be
any value but a consistent naming
strategy is recommended, such as SemVer, CalVer or an incrementing
number. The names "default" and "latest"
are reserved words and cannot be used.
description:
type: string
description: >
Description allows specifying additional information about the
ConnectorVersion, such as what changed
since the last version etc.
x-go-type-skip-optional-pointer: true
isLatest:
type: boolean
description: >-
IsLatest denotes whether this is the latest version of the
Connector.
isDefault:
type: boolean
description: >-
IsDefault denotes whether this is the default version of the
Connector.
createdAt:
type: string
format: date-time
description: CreatedAt is the time at which the ConnectorVersion was created.
updatedAt:
type: string
format: date-time
description: >
UpdatedAt is the time at which the ConnectorVersion was last
updated, including any changes to child
resources.
publishedAt:
format: date-time
description: |
PublishedAt is the time at which the ConnectorVersion was published.
type: string
nullable: true
messages:
type: array
items:
$ref: '#/components/schemas/Message'
x-go-type-skip-optional-pointer: true
required:
- id
- name
- isLatest
- isDefault
- createdAt
- updatedAt
- publishedAt
ErrorField:
description: ErrorField denotes a field which has an error.
type: object
properties:
field:
type: string
description: >
Field is the name of the field which has an error, this may be a
path to a nested field, including array
elements. The format of this field is of the form:
"field1.field2[0].field3"
message:
type: string
description: Message is the error message for this specific field.
required:
- field
- message
Message:
description: >
Message is a message to be displayed to the user to indicate some
information about the
preceding request.
type: object
properties:
text:
description: Text contains the text of the message.
type: string
severity:
$ref: '#/components/schemas/MessageSeverity'
detail:
description: >
Details contains additional information about the message. This is
intended to be used
to provide more information about the message, such as a list of
validation errors.
type: array
items:
type: string
x-go-type-skip-optional-pointer: true
required:
- text
- severity
MessageSeverity:
type: string
enum:
- info
- warning
- error
securitySchemes:
bearerToken:
description: >
Bearer token authentication used by the Versori Platform. External
consumers must provide an API key, however
internal consumers must provide a JWT id_token issued by our IdP.
type: http
scheme: bearer
cookie:
description: Cookie authentication used by the Versori Platform.
type: apiKey
in: cookie
name: cookie
````