Ariadni – SMS and Email Interface Specifications

Version 2.01

1 Introduction

1.1 Scope

The present document specifies the protocols and interfaces in order submit SMS and Emails between Government departments and the Notification Gateway.

1.2 Target Audience

The intended audience for this document are:

Software Designers;
Software Developers;
API Developers.

1.3 Structure of this document

The document is organized as follows:

Chapter 1 – Introduction presents the scope and the terminology used in the document;
- Chapter 2 – Describes the Message Specifications for the Notification Gateway;

2 Notification Gateway Message Specifications

2.1 Supported Message Patterns

The Notification Gateway supports only Synchronous exchange:

– In the synchronous exchange, the consuming client/service waits for a business response message from the Provider service.

2.2 Supported Message Types

The Notification Gateway supports the following message type:

Simple Message: The e-Service should provide the submitted text

Template Message: The e-Service should provide tokens and values that will be replaced in a pre-defined template configured in the Notification Gateway.

2.3 Message Specifications

2.3.1 Base URL

All REST API’s are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.

All URLs referenced in the API documentation have the following base:

https://{FQDN}/DITS.CeGG.DIS.Notifications/api/v1.0

The Production FQDN is: https://dis.gateway.local

The Test FQDN is: https://dis.dev.gateway.local

FQDN: A fully qualified domain name (FQDN) that identifies the connector host.

2.3.2 Swagger Specifications

Swagger specifications can be found in the following url:

https://{FQDN}/swagger

2.3.3 Submit Simple Message

2.3.3.1 HTTP Request

To send a new simple message, make an HTTP POST to the following resource URL. Resource: https://{Base URL}/notification/simple-message

2.3.3.1.1 Authentication

HTTP request to REST API are protected with Basic authentication. In short, you will use your department notification account provided by the Gateway Team.

2.3.3.1.2 Payload

The payload must be a valid JSON object of type «Simple Message» as specified at section 2.4.1

2.3.3.2 HTTP Response

2.3.3.2.1 HTTP Headers

2.3.3.2.2 X-RequestID

The HTTP header is always returned. Contains the Message ID generated by the API. You may use this for troubleshooting.

2.3.3.2.3 Possible HTTP status Codes

HTTP Status	Description
200 OK	The request was successful.
401 UNAUTHORIZED	The supplied credentials, if any, are not sufficient to access the resource.
400 BAD REQUEST	Empty request body or not valid message or not valid JSON object.
404 NOT FOUND	The server cannot find the requested resource.
500 INTERNAL SERVER ERROR	Indicates that the server encountered an unexpected condition that prevented from fulfilling the request.

2.3.3.2.4 Successful Response Format

When the HTTP Status Code is 200 ?? then the response body is a JSON object of

«SendMessageResponse» (see section 2.4).

2.3.3.2.5 Error Response Format

The REST API will return an «ErrorResponse» JSON object in the HTTP response body when something goes wrong.

2.3.4 Submit Template Message

2.3.4.1 HTTP Request

2.3.4.1.1 Authentication

HTTP request to this endpoint is protected with Basic authentication. In short, you will use your department notification account provided by the Gateway Team.

2.3.4.1.2 Payload

The payload must be a valid JSON object of type «Template Message» as specified at section 2.4.2

2.3.4.2 HTTP Response

2.3.4.2.1 HTTP Headers

2.3.4.2.2 X-RequestID