Products Downloads


French version


 

The AMBSS provides a set of REST Web services used to generate Adelia subscribers via the four basic CRUD operations: Create, Read, Update, Delete.

These services are divided into two groups:

  • Services for managing configuration objects: the equivalent of the configurations section of the subscribersConf.yml configuration file,
  • services for managing subscriber files: the equivalent of the subscribers section of the subscribersConf.yml configuration file.


Swagger documentation can be accessed via the URL:

http://<hostname>:<port_number>/ambss/swagger-ui/index.html


All these Web services handle data in JSON format.


Note:

By default, these services manage configurations and subscribers stored in memory. The 'ambss.subscribers.writer' property is used to enable the saving of subscriber creations and changes by REST web services in the Adelia subscriber configuration file (the default value is "false"). If no subscriber configuration file is specified when the AMBSS is started, a subscribersConf.yml file is created in the AMBSS root directory (the parent directory of the config sub-directory where the application-dev.yml file is).

REST service configurations

These are accessible via the URL:

http://<hostname>:<port_number>/ambss/v1/configurations , where "hostname" is the name of the machine hosting the Sprint Boot AMBSS application, "port_number" is the TCP listening port number for the AMBSS (in the application.yml or application-dev.yml application).

Creating a configuration

HTTP method

POST

URL

http://<port_number>/ambss/v1/configurations

RolesADMIN ('ambss.security.role-names.admin-role' property)
Parameters in the URL
  • write: Integer (0 or 1). For this request, enables the 'ambss.subscribers.writer' property value to be exceeded and the created configuration to be saved or not saved (0 value to not save; 1 to save).
Request body

Message in JSON format describing the configuration to add. Based on this example, it is:

{
  "id": "partialConfigBrokerConfig",
  "brokerConfig": null,
  "factory": {
    "id": "com.hardis.adelia.ambss.rabbitmq.amqp.RabbitmqAMQPSubscriberFactory"
  },
  "brokerConnection": {
    "password": "guest",
    "username": "guest"
  },
  "subscribeTopic": {
    "consumerPrefetchCount": 1000,
    "autoAck": false,
    "queue": null
  },
  "declarePassive": true,
  "name": "order_event_queue"
}
Response code
  • 201 (Created): Operation was successful.
  • 400 (Bad request): The syntax of the configuration in JSON format is incorrect.
  • 409 (Conflict): An <id_config> identifier configuration already exists.
  • 500 (Internal server error): An internal error occurred.
Response body

No response if successful (code 201); JSON object detailing the error if not:

{
    "timestamp": 1648458350039,
    "status": 400,
    "error": "Bad Request",
    "message": "Validation failed for object='configurationEntity'. Error count: 1",
    "path": "/ambss/v1/configurations"
}

Read

Several read operations enable information on the configurations to be retrieved.


Reading a configuration

HTTP method

GET

URL

http://<port_number>/ambss/v1/configurations/<id_config>

RolesUSER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)
Response code
  • 200 (OK): Operation was successful.
  • 404 (Not Found): The <id_config> identifier configuration does not exist.
  • 500 (Internal server error): An internal error occurred.
Response bodyIf successful (code 200), <id_config> identifier configuration in JSON format; JSON object detailing the error if not


List of configurations

This method retrieves all the created configurations, optionally applying search filters.

HTTP method

GET

URL

http://<port_number>/ambss/v1/configurations

RolesUSER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)
Parameters in the URL
  • id: Configuration identifier pattern (regular expression),
  • adeliaPoolName: Adelia connections pool name pattern (regular expression),
  • factory.id: Identifier pattern (regular expression) of the factory contained in the configuration,
  • adeliaPgm.objectFileName: Pattern (regular expression) of the object file name resulting from the 3GL generation of the EADELIA program contained in the configuration,
  • adeliaPgm.javaPackage: Pattern (regular expression) of the Java package name defined for the 3GL generation of the associated EADELIA program contained in the configuration,
  • adeliaPgm.customObjectMapper : Pattern (regular expression) of the Java bean identifier defined in the beans-context.xml file used to configure the properties to convert a JSON object to an Adelia class instance contained in the configuration.

Example:

http://<port_number>/ambss/v1/configurations?id=partial.*&adeliaPgm.objectFileName=EAP\d+

Response code
  • 200 (OK): Operation was successful.
  • 404 (Not Found): The <id_config> identifier configuration does not exist.
  • 500 (Internal server error): An internal error occurred.
Response bodyIf successful (code 200), list in JSON format of configurations meeting the applied filter criteria; JSON object detailing the error if not.


List of subscribers associated with a configuration

HTTP method

GET

URL

http://<port_number>/ambss/v1/configurations/<id_config>/subscribers

RolesUSER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)
Response code
  • 200 (OK): Operation was successful.
  • 404 (Not Found): The <id_config> identifier configuration does not exist.
  • 500 (Internal server error): An internal error occurred.
Response body

If successful (code 200), list in JSON format of subscribers with a reference to the <id_config> identifier configuration in the description; JSON object detailing the error if not.

Note: Each returned subscriber is returned in the non-deduced version (i.e. without replacing all the references used by the referenced objects).


Updating a configuration

HTTP method

PUT

URL

http://<port_number>/ambss/v1/configurations/<id_config>

RolesADMIN ('ambss.security.role-names.admin-role' property)
Parameters in the URL
  • write: Integer (0 or 1). For this request, enables the 'ambss.subscribers.writer' property value to be exceeded and the created configuration to be saved or not saved (0 value to not save; 1 to save).
Response code
  • 204 (No Content): Operation was successful.
  • 400 (Bad Request): The syntax of the configuration in JSON format is incorrect or the syntax deduced from the subscriber that references this configuration is not valid (by applying the new configuration).
  • 404 (Not Found): The <id_config> identifier configuration does not exist.
  • 405 (Method Not Allowed): The <id_config> identifier configuration could not be updated because it is referenced by at least one subscriber in "started" state.
  • 500 (Internal server error): An internal error occurred.
Response bodyNo response if successful (code 204); JSON object detailing the error if not.

Deleting a configuration

HTTP method

DELETE

URL

http://<port_number>/ambss/v1/configurations/<id_config>

RolesADMIN ('ambss.security.role-names.admin-role' property)
Parameters in the URL
  • write: Integer (0 or 1). For this request, enables the 'ambss.subscribers.writer' property value to be exceeded and the created configuration to be saved or not saved (0 value to not save; 1 to save).
Response code
  • 204 (No Content): Operation was successful.
  • 404 (Not Found): The <id_config> identifier configuration does not exist.
  • 405 (Method Not Allowed): The <id_config> identifier configuration could not be deleted because it is referenced by at least one subscriber.
  • 500 (Internal server error): An internal error occurred.
Response bodyNo response if successful (code 204); JSON object detailing the error if not.

↑ Top of page

REST service subscribers

These are accessible via the URL:

http://<hostname>:<port_number>/ambss/v1/subscribers, where "hostname" is the name of the machine hosting the Sprint Boot AMBSS application and "port_number" is the TCP listening port configured for the AMBSS (in the application.yml or application-dev.yml file).


Creating a subscriber

HTTP method

POST

URL

http://<port_number>/ambss/v1/subscribers

Roles

ADMIN ('ambss.security.role-names.user-role' property)

Parameters in the URL

  • write: Integer (0 or 1). For this request, enables the 'ambss.subscribers.writer' property value to be exceeded and the created configuration to be saved or not saved (0 value to not save; 1 to save).

Request body

Message in JSON format describing the subscriber to add. Based on this example, it is:

{
  "id": "subUsingTwoPartialConfigAndComplete",
  "startOnCreation": true,
  "config": {
    "$ref": [
      "/configurations/partialConfigAdeliaPgm",
      "/configurations/partialConfigBrokerConnection"
    ],
    "brokerConfig": {
      "subscribeTopic": {
        "consumerPrefetchCount": 1000,
        "autoAck": false,
        "queue": {
          "declarePassive": true,
          "name": "order_event_queue"
        }
      }
    }
  }
}

Notes: 

      • The description in JSON format of the subscriber may or may not have a reference to one or more configurations. Creation is only authorized if the deduced description (i.e. replacing all the references used by the referenced objects) is complete and valid.
      • The "id" attribute is not mandatory. If it is not entered, the AMBSS assigns it a random and unique alphanumeric value.

Response code

  • 201 (Created): Operation was successful.

  • 400 (Bad request): The syntax of the subscriber's description in JSON format is incorrect or the subscriber refers to an unknown configuration.

  • 409 (Conflict): An <id_subscriber> identifier subscriber already exists.

  • 500 (Internal server error): An internal error occurred.

Response body

No response if successful (code 201); JSON object detailing the error if not:

{
    "timestamp": 1648479612407,
    "status": 400,
    "error": "Bad Request",
    "message": "Subscriber with id 'subTemperature' is not valid. Validation failed for subscriber 'subTemperature'. Config object must only contain valid reference(s) to existing configuration(s)",
    "path": "/ambss/v1/subscribers"
}

If successful, the response header contains a "Location" attribute the value of which is the URL with read access to the created subscriber (in the example above, the Location header will contain: http://localhost:8080/ambss/v1/subscribers/subUsingTwoPartialConfigAndComplete)


Starting a subscriber

HTTP method

GET

URL

http://<port_number>/ambss/v1/subscribers/<id_subscriber>/start

Roles

USER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)

Response code

  • 200 (OK): Operation was successful.

  • 404 (Not Found): The <id_subscriber> identifier subscriber does not exist.

  • 405 (Method Not Allowed): The <id_subscriber> identifier subscriber could not start as it is not in the right state ("stopped" state).

  • 500 (Internal server error): An internal error occurred.

Response body

If successful (code 200), <id_subscriber> identifier subscriber description in its deduced form in JSON format; JSON object detailing the error if not.


Stopping a subscriber

HTTP method

POST

URL

http://<port_number>/ambss/v1/subscribers/<id_subscriber>/stop

Roles

USER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)

Request body

Message in JSON format describing the subscriber stop parameters. These parameters depend on the factory and broker associated with the subscriber.

Kafka

No parameters (empty JSON object). See the 'config/brokerConfig/subscribeTopic/stopImmediate' property for the native subscriber stop behavior.

MQTT v3

No parameters (empty JSON object).

MQTT v5

No parameters (empty JSON object).

Nats Jetstream

closeAfterBatch

Boolean. Default value: "false". Equivalent to the BRK_RESPONSE '*STOP_AFTER_BATCH' instruction           

RabbitMQ AMQP

No parameters (empty JSON object). 

Redis Pub/Sub

No parameters (empty JSON object).

Response code

  • 200 (OK): Operation was successful.

  • 404 (Not Found): The <id_subscriber> identifier subscriber does not exist.

  • 405 (Method Not Allowed): Identifier subscriber <id_subscriber> could not start due to being in the incorrect state ("stopped" state).

  • 500 (Internal server error): An internal error occurred.

Response body

If successful (code 200), <id_subscriber> identifier subscriber description in its deduced form in JSON format; JSON object detailing the error if not.


Read

Several read operations enable information on the subscribers to be retrieved.

Reading a subscriber

HTTP method

GET

URL

http://<port_number>/ambss/v1/subscribers/<id_subscriber>

Roles

USER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)

Response code

  • 200 (OK): Operation was successful.

  • 404 (Not Found): The <id_subscriber> identifier subscriber does not exist.

  • 500 (Internal server error): An internal error occurred.

Response body

If successful (code 200), <id_subscriber> identifier subscriber description in its deduced form in JSON format; JSON object detailing the error if not.


Subscriber list

This method retrieves all the created subscriptions, optionally applying search filters.

HTTP method

GET

URL

http://<port_number>/ambss/v1/subscribers

Roles

USER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)

Parameters in the URL

  • id: Subscriber identifier pattern (regular expression),

  • adeliaPoolName: Adelia connections pool name pattern (regular expression),

  • factory.id: Identifier pattern (regular expression) of the factory contained in the subscriber description,

  • adeliaPgm.objectFileName: Pattern (regular expression) of the object file name resulting from the 3GL generation of the EADELIA program contained in subscriber description,

  • adeliaPgm.javaPackage: Pattern (regular expression) of the Java package name defined for the 3GL generation of the associated EADELIA program contained in the description of the,

  • adeliaPgm.customObjectMapper: Pattern (regular expression) of the Java bean identifier defined in the beans-context.xml file used to configure the properties to convert a JSON object to an Adelia class instance contained in the subscriber description,

  • state.code: Subscriber state,

Example:

http://<port_number>/ambss/v1/ subscribers?id=sensor.*&adeliaPgm.objectFileName=EAP\d+&state.code=2

Response code

  • 200 (OK): Operation was successful.

  • 404 (Not Found): The <id_subscriber> identifier subscriber does not exist.

  • 500 (Internal server error): An internal error occurred.

Response body

If successful (code 200), list in JSON format of subscriber descriptions (in their deduced form) meeting the applied filter criteria; JSON object detailing the error if not.


List of configurations associated with a subscriber

HTTP method

GET

URL

http://<port_number>/ambss/v1/subscribers/<id_subscriber>/configurations

Roles

USER ('ambss.security.role-names.user-role' property) and ADMIN ('ambss.security.role-names.admin-role' property)

Response code

  • 200 (OK): Operation was successful.

  • 404 (Not Found): The <id_subscriber> identifier subscriber does not exist.

  • 500 (Internal server error): An internal error occurred.

Response body

If successful (code 200), list in JSON format of configurations referenced by the <id_subscriber> identifier subscriber; JSON object detailing the error if not.

Subscriber state

When a subscriber is created, the AMBSS associates a state ("state" object) with it in its description. It appears when using subscriber read APIs. The state includes the following information:

Name

Type

Description

code

Integer of 1, 2 or 3

Subscriber state:

  • STOP (1): The subscriber is stopped.

  • START (2): The subscriber is started.

  • DELETE (3): The subscriber is deleted.

internalCode

Integer of 21 to 26

Internal state of the subscriber:

  • init (21): Initial state when the subscriber is created

  • idle (22): Idle state of the subscriber

  • on_start (23): State when handling the on_start event

  • on_message (24): State when handling the on_message event

  • on_error (25): State when handling the on_error event

  • on_stop (26): State when handling the on_stop event

errorCode

Integer

Error code when the subscriber is in the internal on_error state (25)

errorMessage

Alphanumeric

Error code message (errorCode)


Below is a list of possible error codes for a subscriber:

Error number

Error message

Immediate stop

-101

The factory's Java class cannot be found.

Yes

-102

The factory's Java class does not implement the correct interface or inherit the correct class.

Yes

-103

Error when obtaining the factory constructor.

Yes

-104

Error when creating the factory instance.

Yes

-105

The 'getFactory' static method cannot be found in the factory class.

Yes

-106

Error when calling the 'getFactory' method in the factory class.

Yes

-107

The 'getFactory' static method must return the correct type of instance.

Yes

-108

The customObjectMapper property does not match an existing bean identifier.

Yes

Error number

Error message

Immediate stop

-301

Error when validating the broker connection configuration.

Yes

-302

Error when validating the topic subscription configuration.

Yes

-401

Error when creating the topic pattern.

Yes

-402

Error when starting the EADELIA program.

Yes

-403

Error when handling the ON_START event: negative acknowledgment sent.

Yes

-404

Error when creating the Kafka consumer configuration from the broker connection configuration.

Yes

-501

Error when converting an Avro pojo to an Adelia pojo.

No

Error number

Error message

Immediate stop

-301

Error when validating the broker connection configuration.

Yes

-302

Error when validating the broker's topic subscription configuration.

Yes

-401

Error when creating Paho MQTTv3 connection options based on the broker connection configuration.

Yes

-402

Error when creating the Paho MQTTv3 client using the options.

Yes

-403

Error when connecting the Paho MQTTv3 client to the broker.

Yes

-404

Error when subscribing the Paho MQTTv3 client to the topics.

Yes

-405

Error when starting the EADELIA program.

Yes

-406

Error when handling the ON_START event: negative acknowledgment sent.

Yes

-501

Broker connection lost.

Yes / No

-502

Error when force disconnecting the Paho MQTTv3 client.

Yes

-503

Error when closing the Paho MQTTv3 client.

Yes

Error number

Error message

Immediate stop

-301

Error when validating the broker connection configuration.

Yes

-302

Error when validating the broker's topic subscription configuration.

Yes

-401

Error when creating Paho MQTTv5 connection options based on the broker connection configuration.

Yes

-402

Error when creating the Paho MQTTv5 client using the options.

Yes

-403

Error when connecting the Paho MQTTv5 client to the broker.

Yes

-404

Error when subscribing the Paho MQTTv5 client to the topics.

Yes

-405

Error when starting the EADELIA program.

Yes

-406

Error when handling the ON_START event: negative acknowledgment sent.

Yes

-501

Broker connection lost.

Yes / No

-502

Error when force disconnecting the Paho MQTTv5 client.

Yes

-503

Error when closing the Paho MQTTv5 client.

Yes

Error number

Error message

Immediate stop

-301

Error when validating the broker connection configuration.

Yes

-302

Error when validating the topic subscription configuration.

Yes

-401

Error when creating NATS connection options based on the broker connection configuration.

Yes

-402

Error when creating the NATS connection using the connection options.

Yes

-403

Error when creating JetStream subscription options based on the topic subscription configuration.

Yes

-404

Error when creating the JetStream context.

Yes

-405

Error when creating JetStream context options based on the broker connection configuration.

Yes

-406

Error when subscribing to JetStream broker topics.

Yes

-407

Error when starting the EADELIA program.

Yes

-408

Error when handling the ON_START event: negative acknowledgment sent.

Yes

-501

Error when unsubscribing from JetStream broker topics.

Yes

-502

Error when closing the NATS connection to the broker.

Yes

Error number

Error message

Immediate stop

-301

Error when validating the broker connection configuration.

Yes

-302

Error when validating the broker's topic subscription configuration.

Yes

-401

Error when configuring the SSL connection: key management exception for all operations concerning key management.

Yes

-402

Error when creating the AMQP connection.

Yes

-403

Error when creating the AMQP channel.

Yes

-404

Error when passively declaring the queue.

Yes

-405

Error when declaring the queue.

Yes

-406

Error during basic consumption in the queue.

Yes

-407

Error when calling channel.basicQos.

Yes

-408

Error when passively declaring the exchanger.

Yes

-409

Error when declaring the exchanger.

Yes

-410

Error when binding the queue.

Yes

-411

Error when starting the EADELIA program.

Yes

-412

Error when handling the ON_START event: negative acknowledgment sent.

Yes

-413

Error when creating RabbitMQ connection options based on the broker connection configuration.

Yes

-501

Error when closing the channel.

Yes

-502

Error when closing the connection.

Yes

-503

Connection closure not initiated by the application.

Yes

-504

The subscriber was cancelled by the broker.

Yes

Error number

Error message

Immediate stop

-301

Error when validating the broker connection configuration.

Yes

-302

Error when validating the topic subscription configuration.

Yes

-401

Error when creating the Redis URI based on the broker connection configuration.

Yes

-402

Error when creating the ClientOptions/ClusterClientOptions options object based on the broker connection configuration.

Yes

-403

Error when creating the Pub/Sub connection to the Redis broker.

Yes

-404

Error when subscribing to broker channels and models.

Yes

-405

Error when starting the EADELIA program.

Yes

-406

Error when handling the ON_START event: negative acknowledgment sent.

Yes

-501

Error when closing the connection to the Redis broker.

Yes

-502

Error when closing the Redis client.

Yes

-503

Lettuce Redis client closed due to loss of connection to the broker.

Yes

-504

Lettuce Redis client closed due to a communication error with the broker.

Yes

Updating a subscriber

HTTP method

PUT

URL

http://<port_number>/ambss/v1/subscribers/<id_subscriber>

Roles

ADMIN ('ambss.security.role-names.admin-role' property)

URL parameters

  • write: Integer (0 or 1). For this request, enables the 'ambss.subscribers.writer' property value to be exceeded and the created configuration to be saved or not saved (0 value to not save; 1 to save).

Response code

  • 204 (No Content): Operation was successful.

  • 400 (Bad Request): The syntax of the subscriber's description in JSON format is incorrect or the subscriber refers to an unknown configuration.

  • 404 (Not Found): The <id_subscriber> identifier subscriber does not exist.

  • 405 (Method Not Allowed): The description of identifier subscriber <id_subscriber> could not be updated due to being in the incorrect state ("stopped" state).

  • 500 (Internal server error): An internal error occurred.

Response body

No response if successful (code 204); JSON object detailing the error if not.


Deleting a subscriber

HTTP method

DELETE

URL

http://<port_number>/ambss/v1/subscribers/<id_subscriber>

Roles

ADMIN ('ambss.security.role-names.admin-role' property)

URL parameters

  • write: Integer (0 or 1). For this request, enables the 'ambss.subscribers.writer' property value to be exceeded and the created configuration to be saved or not saved (0 value to not save; 1 to save).

Response code

  • 204 (No Content): Operation was successful.

  • 404 (Not Found): The <id_subscriber> identifier subscriber does not exist.

  • 405 (Method Not Allowed): The <id_subscriber> identifier subscriber could not be deleted due to being in the incorrect state ("stopped" state).

  • 500 (Internal server error): An internal error occurred.

Response body

No response if successful (code 204); JSON object detailing the error if not.

↑ Top of page

REST service access authentication

When using the AMBSS in development (via ambss-dev. scripts), authentication is disabled.

When using the AMBSS in production (via ambss. scripts), authentication is enabled by default. To disable it, set the 'ambss.security.enabled' property to "false" in the application.yml configuration file.


A section specifies how to configure access authentication. This is done using a JWT token. This must define one of the two possible roles for running REST services (user or administrator role).


Set of examples

The AMBSS offers API test support for examples of use (MQTT broker). Knowledge of how to use a REST client such as Insomnia or Postman is required.


↑ Top of page

  • Aucune étiquette