Create Definitions - Versori User Documentation

POST

{organisation_id}

connectors

{connector_id}

versions

{version}

definitions

Create Definitions

curl --request POST \
  --url https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "definitions": [
    {
      "name": "<string>",
      "accept": [
        "<string>"
      ],
      "schema": {
        "contentType": "application/schema+json",
        "content": "<string>"
      },
      "description": "<string>"
    }
  ]
}
'

import requests

url = "https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions"

payload = { "definitions": [
        {
            "name": "<string>",
            "accept": ["<string>"],
            "schema": {
                "contentType": "application/schema+json",
                "content": "<string>"
            },
            "description": "<string>"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    definitions: [
      {
        name: '<string>',
        accept: ['<string>'],
        schema: {contentType: 'application/schema+json', content: '<string>'},
        description: '<string>'
      }
    ]
  })
};

fetch('https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'definitions' => [
        [
                'name' => '<string>',
                'accept' => [
                                '<string>'
                ],
                'schema' => [
                                'contentType' => 'application/schema+json',
                                'content' => '<string>'
                ],
                'description' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions"

	payload := strings.NewReader("{\n  \"definitions\": [\n    {\n      \"name\": \"<string>\",\n      \"accept\": [\n        \"<string>\"\n      ],\n      \"schema\": {\n        \"contentType\": \"application/schema+json\",\n        \"content\": \"<string>\"\n      },\n      \"description\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"definitions\": [\n    {\n      \"name\": \"<string>\",\n      \"accept\": [\n        \"<string>\"\n      ],\n      \"schema\": {\n        \"contentType\": \"application/schema+json\",\n        \"content\": \"<string>\"\n      },\n      \"description\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"definitions\": [\n    {\n      \"name\": \"<string>\",\n      \"accept\": [\n        \"<string>\"\n      ],\n      \"schema\": {\n        \"contentType\": \"application/schema+json\",\n        \"content\": \"<string>\"\n      },\n      \"description\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "definitions": [
    {
      "id": "<string>",
      "name": "<string>",
      "accept": [
        "<string>"
      ],
      "url": "<string>",
      "description": "<string>",
      "referencedBy": [
        {
          "type": "definition",
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  ]
}

{
  "code": "<string>",
  "message": "<string>",
  "fields": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<string>"
}

Authorizations

Authorization

string

header

required

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.

Path Parameters

organisation_id

string<ulid>

required

connector_id

string<ulid>

required

ID is the unique identifier of the Connector.

version

string

required

Version is the version name of the Connector to retrieve. The reserved names "latest" and "default" may be used to retrieve the latest version or the default version respectively.

Body

application/json

DefinitionsCreate is the payload used to create new Definitions. Each definition can reference another definition in the same request using the following syntax:

{
  "$ref": "#/$defs/{definition_name}"
}

New definitions may also reference existing definitions, however they use the proper URL syntax:

{
  "$ref": "https://platform.versori.com/api/schemas/v1/o/{organisation_id}/{connector_id}/{connector_version}/{definition_id}.{media_type_ext}"
}

Note, the $refs stored in GCS are the gs:// URLs. The API must transform the URLs to the correct public URL. Ideally, the Definition's name would be in the URL, but this would cause issues if a user wanted to rename a Definition, which is something I think we should support. For now using id is fine, but if we changed to in the future, we'd need a way to iterate over all Definitions referencing the one being renamed and update the $ref URLs.

For referencing existing definitions, the definition name must already exist within the scope of the current Connector and Version.

Each definition must have matching dataMediaTypes and schema.mediaType values.

definitions

object[]

required

Show child attributes

Response

Created

Definitions is a list of Definition objects. This is a non-paginated list and contains all definitions related to the originating request (i.e. all created Definitions in a CreateDefinitions request).

definitions

object[]

required

Show child attributes

⌘I

Create Definitions

curl --request POST \
  --url https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "definitions": [
    {
      "name": "<string>",
      "accept": [
        "<string>"
      ],
      "schema": {
        "contentType": "application/schema+json",
        "content": "<string>"
      },
      "description": "<string>"
    }
  ]
}
'

import requests

url = "https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions"

payload = { "definitions": [
        {
            "name": "<string>",
            "accept": ["<string>"],
            "schema": {
                "contentType": "application/schema+json",
                "content": "<string>"
            },
            "description": "<string>"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    definitions: [
      {
        name: '<string>',
        accept: ['<string>'],
        schema: {contentType: 'application/schema+json', content: '<string>'},
        description: '<string>'
      }
    ]
  })
};

fetch('https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'definitions' => [
        [
                'name' => '<string>',
                'accept' => [
                                '<string>'
                ],
                'schema' => [
                                'contentType' => 'application/schema+json',
                                'content' => '<string>'
                ],
                'description' => '<string>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions"

	payload := strings.NewReader("{\n  \"definitions\": [\n    {\n      \"name\": \"<string>\",\n      \"accept\": [\n        \"<string>\"\n      ],\n      \"schema\": {\n        \"contentType\": \"application/schema+json\",\n        \"content\": \"<string>\"\n      },\n      \"description\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"definitions\": [\n    {\n      \"name\": \"<string>\",\n      \"accept\": [\n        \"<string>\"\n      ],\n      \"schema\": {\n        \"contentType\": \"application/schema+json\",\n        \"content\": \"<string>\"\n      },\n      \"description\": \"<string>\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://platform.versori.com/api/connect/v1/o/{organisation_id}/connectors/{connector_id}/versions/{version}/definitions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"definitions\": [\n    {\n      \"name\": \"<string>\",\n      \"accept\": [\n        \"<string>\"\n      ],\n      \"schema\": {\n        \"contentType\": \"application/schema+json\",\n        \"content\": \"<string>\"\n      },\n      \"description\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "definitions": [
    {
      "id": "<string>",
      "name": "<string>",
      "accept": [
        "<string>"
      ],
      "url": "<string>",
      "description": "<string>",
      "referencedBy": [
        {
          "type": "definition",
          "id": "<string>",
          "name": "<string>"
        }
      ]
    }
  ]
}

{
  "code": "<string>",
  "message": "<string>",
  "fields": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<string>"
}