SF-001 Application info

    Namespace: synergy/app-info Last updated: 27.10.2017

    Introduction

    The ability to discover information about applications in a hosted environment is essential from an integration perspective. Such information include features/services offered by the application and application’s type and/or identity. This documents describes how such information is gathered and how it is offered by Chemaxon Cloud to registered applications.

    Registering application

    Basic protocol

    Each application MUST provide a JSON document which contains information about application’s address, name, identity and supported features.

    {
      "displayName": "Fibonacci",
      "address": "http://localhost:8102",
      "identities": [{ "category": "service", "type": "computation" }],
      "features": [
        {
          "namespace": "synergy/app-info",
          "attributes": {
            "url": "http://localhost:8102/services/app-info"
          }
        },
        {
          "namespace": "synergy/health",
          "attributes": {
            "url": "http://localhost:8102/services/health"
          }
        },
        {
          "namespace": "synergy/icon",
          "attributes": {
            "url": "http://localhost:8102/services/app-icon"
          }
        }
      ]
    }
    • displayName - application name displayed in Chemaxon Cloud
    • address - base url address of the application
    • features - list of available features with configuration
    • identities - list of application identities

    This JSON should be exposed at a publicly available URL with a content type of “application/json; charset=utf-8”.

    Identities

    Application is easily categorised by its list of identities which can be used for navigation, grouping and integration based on identity. Application identity is described by category and type. Application can have more than one identity (see examples).

    • category - is an area, functionality or capability that is described in this block.
    • type - the quality or implementation of the category.

    Values of the categories and types are validated and should be set according to this documentation otherwise the registration will be blocked. The following categories are mandatory but other custom ones can be added without any limitation.

    category type
    application webapp
    service
    group reporting
    registration
    design
    compliance
    computation
    search
    eln
    inventory
    vendor chemaxon
    product plexus-connect
    compound-registration
    assay
    marvin-live
    compliance-checker
    chemlocator
    navigator

    Features

    Every application SHOULD have list of SF-XXX features. Every feature contains a namespace and map of attributes describing the configuration required for a given feature.

    • namespace - sensible identifier of the feature (like product/feature-name, workflow-name/feature-name and so on), synergy/* is the reserved namespace for the features used by the synergy
    • attributes - map of feature attributes. Number of items inside attributes is not limited and it depends on the feature what attributes are necessary for using the feature

    Chemaxon Cloud also defines few features required from applications for its own functionality.

    feature namespace documentation
    Application Info synergy/app-info SF-001
    Healthcheck synergy/health SF-002
    Application Icon synergy/icon SF-003
    Web endpoints (optional) synergy/web SF-004

    Discovering applications

    Basic protocol

    Chemaxon Cloud provides /api/discover endpoint where applications can send HTTP GET request for list of available applications and their application info. Request has to be authenticated using JWT token header (see Application authentication page) either for current user or service itself.

    Example

    GET /api/discover
    [
      {
        "displayName": "Fibonacci",
        "address": "http://localhost:8102",
        "identities": [{ "category": "service", "type": "computation" }],
        "features": [
          {
            "namespace": "synergy/app-info",
            "attributes": {
              "url": "http://localhost:8102/services/app-info"
            }
          },
          {
            "namespace": "synergy/health",
            "attributes": {
              "url": "http://localhost:8102/services/health"
            }
          },
          {
            "namespace": "synergy/icon",
            "attributes": {
              "url": "http://localhost:8102/services/app-icon"
            }
          }
        ]
      },
      {
        "displayName": "Plexus Analysis",
        "address": "http://localhost:9005",
        "identities": [
          { "category": "plexus", "type": "analysis" },
          { "category": "application", "type": "data-analysis" }
        ],
        "features": [
          {
            "namespace": "synergy/app-info",
            "attributes": {
              "url": "http://localhost:9005/plexus-analysis/synergy/analysis/app-info"
            }
          },
          {
            "namespace": "synergy/health",
            "attributes": {
              "url": "http://localhost:9005/plexus-analysis/synergy/analysis/health"
            }
          },
          {
            "namespace": "synergy/icon",
            "attributes": {
              "url": "http://localhost:9005/plexus-analysis/synergy/analysis/app-icon"
            }
          },
          {
            "namespace": "synergy/web",
            "attributes": {
              "mainEntryPoint": "http://localhost:9005/plexus-analysis/login"
            }
          }
        ]
      }
    ]

    Configuration

    Application info uses synergy/app-info namespace and single url attribute.

    {
      "namespace": "synergy/app-info",
      "attributes": {
        "url": "http://localhost:8102/services/app-info"
      }
    }