Apps development

• Introduction
  • App frontend
  • Requirements
  • Authorization
• Installation
  • Info request
  • Install request
  • Remove request
• Configuration
  • Config get
  • Config set

Introduction

Applications are a way to extend Heseya. They allow you to create entirely new functionality or integrate with external systems.

The core component of the application is its API. Through a special JSON definition, it declares what kind of microservice it is, what permissions it requires and what configuration options it has. The application (as long as it has the right permissions) has access to almost all endpoints. (omitting endpoints directly related to the user like changing passwords, etc.)

One application instance can support one or many Heseya stores. All these stores will share the same microservice code, however, each will have its own configuration.

App frontend

In some cases, it may be required to modify the Heseya dashboard to enable application management. Heseya use micro-fronts to allows you to easily add any new functionality to the dashboard.

Requirements

The application can be written in any technology. The only requirements are, that the API be available at a Heseya-accessible URL. The app must provide several endpoints, which are described later in this document.

Authorization

Applications use a different authorization scheme than users. You can find documentation here.

Installation

Important assumptions in the topic of application installation:

• The user can grant only those permissions that he or she has.
• During installation, API creates roles that have all the internal privileges of this application; This role is automatically given to the user installing the application.
• To recognize from which API the request was received, you should use the X-Core-Url header. If IdentityToken is present, it should check that the claim iss from the token, is the same as the header.

Required endpoints

The following endpoints must be implemented.

Info request

[GET] /

Information about the application and the required permissions.

Response

{
  "name": "string",
  "author": "string",
  "version": "string",
  "api_version": "string", // minimal api version - e.g. '^3.0.0'
  "icon": "string", // optional
  "description": "string", // optional
  "licence_required": false, // optional
  "microfrontend_url": "string", // optional
  "required_permissions": ["string", "string"],
  "optional_permissions": ["string", "string"], // optional
  "internal_permissions": [
    {
      "name": "string",
      "display_name": "string",
      "description": "string", // optional
      "unauthenticated": false // whether the permission should be given by default to unauthenticated users - optional
    }
  ],
  "widgets": [] // optional
}

Install request

[POST] /install

Payload

{
  "api_url": "string",
  "api_name": "string", // optional
  "api_version": "string", // current api version - e.g. '3.0.0'
  "licence_key": "string", // optional
  "integration_token": "string",
  "refresh_token": "string"
}

Response

{
  "uninstall_token": "string"
}

Remove request

[POST] /uninstall

The application recognizes the API by the token, then performs any operations associated with removing Heseya instance from its database.

Payload

{
  "uninstall_token": "string"
}

Response

Response status: 204 No Body

Configuration

This part is fully optional.

Core API allows apps to have config saved simple config. For more complex configurations, we recommend the use of a micro-front.

Endpoints

Config get

[GET] /config

The value field is returned only for authorized users, while the rest of the data is available to the public.

Response

[
  {
    "key": "string",
    "label": "string",
    "placeholder": "string", // optional
    "type": "string", // enum - text | select | number | color | date | datetime-local
    "default_value": "any",
    "value": "any", // optional
    "required": false, // optional
    "options": [
      { 
        "value": "string",
        "label": "string"
      }
    ],
  }
]

Config set

[POST] /config

App configuration update. The object keys correspond to the key field returned by the endpoint.

Payload

{
    "key1": "value",
    "key2": "value"
}

Response

Response status: 204