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).
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:
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.
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_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).
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 body
No response if successful (code 204); JSON object detailing the error if not.
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 body
No response if successful (code 204); JSON object detailing the error if not.
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).
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:
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)
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.
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.
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)
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,
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
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.
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.
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.
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.
