Dexi Developer Portal

App Developer Portal

Welcome to the App Developer portal for dexi.io.

Here you'll find resources for developing apps and integrations on dexi.io.

Get Started    

Overview

This page gives you an overview of the dexi.yml app definition format

The dexi.yml you'll see mentioned throughout this documentation describes how dexi.io should interact with your service. This includes configuration, authentication, components and REST endpoints.

Metadata

The top section of the YML format is metadata for the app itself. An exhaustive list of properties are shown below:

PropertyDescriptionExampleRequired?
apiVersionThe API version. Should always be apps.dexi.io/v1.0 at the momentapps.dexi.io/v1.0Yes
kindThe kind of YML document. Should always be App at the momentAppYes
nameA unique identifier for your app. Recommended format is lowercase and snake-casinggoogle-driveYes
titleA human-friendly title for your app.Google DriveYes
descriptionA longer description of what your app provides"Read files from and write files to Google Drive"Yes
categoriesA list of valid app categories. The list of categories is fixed and you must choose one or more of the available categories. Click here for the complete list- files
- database
No
keywordsContains an array of keywords (strings) to help users find your app in the dexi app store.- google
- drive
- files
No
appUrlA url to more information about the app or about your companyhttps://dexi.ioYes

Example:

apiVersion: apps.dexi.io/v1.0
kind: App
name: google-drive
title: Google Drive Integration
description: Connect to Google Drive
categories:
  - files
keywords:
  - google
  - drive
  - files
appUrl: https://dexi.io

Properties

The properties section allows you to specify general values for use throughout the rest of the specification. The values in here are made available as variables - and are most often used for repetitive values that you'd like to be able to change in 1 place.

This section is not required but recommended for storing the "base url" of your service

properties:
  baseUrl: http://my-app.my-public-url.com/
  
# Which can then be referenced like this:
specification:
  validate:
    url: "${baseUrl}/dexi/activations/validate"
    method: POST

App configuration and validation

This section describes what kind of configuration, authentication and validation your app requires.

PropertyDescriptionRequired?
specification.validateThe endpoint for validating the provided configuration.
See "Endpoints" for more information on the format
No
specification.configurationAn object containing all configuration fields. This configuration is prompted when the user activates your app and will be available for all your components.
See Configuration Field Types for a list of field types and how to use them.
No

Example:

specification:
  validate: # Validation end point
    url: "${baseUrl}/dexi/activations/validate"
    method: POST

  configuration: #Configuration fields
    type:
      sortOrder: 1 #To ensure the order is retained add this
      title: "Type" #Label of the field
      required: true #If it is required
      type: enum #Enums allows to select from a list of specific values
      options:
        postgresql: PostgreSQL
        mysql: MySQL
        sqlserver: MS SQL
        sap: SAP Hana DB
        oracle: Oracle DB
      configuration:
        emptyText: Select database type...
    host:
      sortOrder: 2
      title: Host
      required: true
      help: The host of the database
      placeholder: my-database-host.com #Shown in the field when it is empty
      type: string
      dependsOn: [ "type" ] #Only enable this field when other fields have value

Components

The last section contains the actual components for your app. Each component is "single-purpose" and exposes a specific type of functionality. This is defined by its type property.

We currently have 2 groups of component types - "data" and "file" types. The data types are all prefixed with "data-" and deal with structured data such as rows from a database or results from a robot. Meaning data that have a row-like structure of { name: value} and exists as a list.

The basic structure of any component is the same - for further information about the specific components see Data Components, File Components or Other Components .

PropertyDescriptionExampleRequired?
nameLike the app name - this is a code name or identifier. Format is recommended to be lower case and snake-casing.insert-row-into-databaseYes
typeThe type decides what sort of component this is. As mentioned above see further documentation on these elsewhere.data-storageYes
titleA human-readable title for the component. This is what the users sees and will use to determine if this component is what they are looking forWrite row to databaseYes
descriptionA longer description of what the component doesWrites a row to a database and ignores any duplicates it might encounter.Yes
specificationThis is an object that contains the actual details of the component. See further information on this structure for the individual component types as mentioned above this table.See Data Components, File Components or Other ComponentsYes

Example:

components:

- name: write-file-to-googledrive
  type: file-storage
  title: Save file to Google Drive
  description: Saves a file to your Google Drive
  specification:
    configuration:
      path:
        title: Path
        type: string
        help: The base path to the Google Drive folder where you would like the results to be placed.
        placeholder: ${app.defaultPath}
        defaultValue: ${app.defaultPath}
        required: true
    validate:
      url: "${baseUrl}/dexi/component/support/validate"
      method: POST
    endpoint:
      url: "${baseUrl}/dexi/file/storage/write"
      method: POST

Updated about a year ago

Overview


This page gives you an overview of the dexi.yml app definition format

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.