Skip to content
This repository has been archived by the owner on Apr 4, 2023. It is now read-only.

API Documentation

Jump to bottom
Rohit Deshmukh edited this page Aug 24, 2020 · 4 revisions

The following diagram shows the data model of Service Catalog:

Service Catalog Class Diagram

The attributes are described below:

Catalog object consists of:

  • id: unique id of the catalog
  • description: a friendly name or description of the service
  • services: an array of Service objects
  • page: the current page in catalog
  • per_page: number of items in each page
  • total: total number of registered services

Service object consists of:

  • id: unique id of service
  • type: the functional type of the service, preferably in the form <platform>.<service-type>. E.g., "composition.marketplace-service"
  • title: human-readable name of the service
  • description: human-readable description of the service
  • meta: a hash-map for optional meta-information
  • apis: an array of API objects specifying the service’s APIs
  • doc: URL to service documentation
  • ttl: time after which the service should be removed from the catalog, unless it is updated within the timeframe.
  • createdAt: RFC3339 time of service creation
  • updatedAt: RFC3339 time in which the service was lastly updated
  • expiresAt: RFC3339 time in which the service expires and is removed from the catalog (only if TTL is set)

API object consists of:

  • id: unique id of the API
  • title: human-readable name of the API
  • description: human-readable description of the API
  • protocol: the communication protocol used by the API (E.g., HTTP, MQTT, etc.)
  • url: URL to the server/target host (E.g., https://services.example.com, tcp://broker.example.com:1883, etc.) as defined by 'Server Object' in OpenAPI/AsyncAPI specifications
  • spec: the specification of the API as per the Open API Specification (Swagger) standard for synchronous (Request-Response) services or the AsyncAPI Specification standard for asynchronous (PubSub) services
  • meta: a hash-map for optional meta-information

Spec object consists of:

  • mediaType: The media type for the spec URL below
    1. For OpenAPI/Swagger Spec: application/vnd.oai.openapi;version=3.0 (YAML variant) or application/vnd.oai.openapi+json;version=3.0 (JSON only variant)
    2. For AsyncAPI Spec: application/vnd.aai.asyncapi;version=2.0.0 or application/vnd.aai.asyncapi+yaml;version=2.0.0 (YAML variant) or application/vnd.aai.asyncapi+json;version=2.0.0 (JSON only variant)
  • url: URL to external spec document
  • schema: the JSON object for the spec can be added here in case if the external document is not available. In case both are present, the spec in the URL takes precedence

HTTP API

Visit the Swagger UI for the OpenAPI Specifications

MQTT API

Service catalog also supports MQTT for service registration and de-registration.

Service registration is similar to PUT method of REST API. Here, a service uses a pre-configured topic for publishing the message.

The will message of the registered service is used to de-register it from the catalog whenever the service disconnects.

For more information on configuration of MQTT topics for service registration and de-registration and examples, see the Configuration page.

Announcement over MQTT:

Service Catalog announces the service registration status via MQTT using retain messages.

The message topics follow following patterns:

<topic_prefix>/<service_name>/<service_id>/alive : (Retained message) The body contains service description of alive service

<topic_prefix>/<service_name>/<service_id>/dead : (Not retained message) The body contains service description of the 'dead' service

The retained messages are removed whenever service de-registers.

The topic prefix is configured as part of server configuration.

Versioning

API version is based on semver. The version is included as a parameter to the MIME type of all HTTP responses:

application/json;version=X.X.X

Clone this wiki locally