Version 2.0
1 Introduction
1.1 Scope
The present document specifies the protocols and interfaces in order to submit and receive messages between Government departments through the DIS Connector and the Government 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 – An overview of the design of the Government Gateway platform and its components
- Chapter 3 – Describes the Inbound Message Specifications and the Backend System API specifications
- Chapter 4 – Describes the Outbound Message Specifications
2 Department Integration System
2.1 Interface Functional Specifications
Integration with Backend system is achieved though the concept of Department Integration System (DIS).
The overall Gateway platform is consisted by the following five corners:
- C1: Backend system (client) submits an integration message to DIS;
- C2: The sending DIS responsible to receive data from the Backend system and sends data to Government Gateway (GG);
- C3: The Government Gateway is responsible for the security (Authentication, Authorization) and the routing of the messages.
- C4: The receiving DIS responsible to receive data from Government Gateway and notify the Backend system through the available Connectors.
- C5: The receiving Backend System (provider) receiving the integration message.
Therefore, the Agencies Backend system should implement the following interfaces:
- Handle incoming Integration Messages;
- Submit Request messages at DIS Submission interface;
- Submit Status Request Message at DIS Submission interface;
- Submit Response messages at DIS response interface.
2.2 Supported Message Patterns
Gateway platform supports both Synchronous and Asynchronous message exchange:
- In the synchronous exchange, the consuming client waits for a business response message from the provider service.
- In the asynchronous exchange the business response message from the provider service will be returned at a later stage asynchronously to Government Gateway. The consuming client will poll the message from the Government Gateway.
3 Inbound Message Specifications
3.1 Supported Message Patterns
3.1.1 Synchronous
The DIS receives the message from the Government Gateway and then through the available Connectors notifies the Backend API waiting for the response.
3.1.2 Asynchronous
The DIS receives the message from the Government Gateway and then through the available Connectors notifies the Backend API.
If the Backend API accepts the integration message without errors then the DIS notifies the Government Gateway that the message is delivered. At this stage the DIS does not expect any response message. The response message will be submitted from the Backend system at a later stage based on business logic.
If the Backend API cannot accept the integration message the DIS connector will retry again X times, based on configuration, to notify the Backend API. Finally, if the maximum retries exceeded then DIS Connector will move the message to the DIS Failed Queue. It is the responsibility of the Administrator to investigate the reasons of the failure.
3.2 Backend System API Specifications
This section describes the supported integration technologies based on the type of the API implementation.
3.2.1 Gateway Metadata
Web services and DB API’s must understand specific Gateway metadata which are the following:
| Name | Type | Description |
|---|---|---|
| CorrelationID | String | Message id generated by Gateway |
| TransactionID | String | In case the message is related to another request. It will contain the correlation id of the related request |
| UniqueIdentifier | String | Citizen id |
| LegalUniqueIdentifier | String | Organization registration no |
| ClientID | String | Profile id of the sender |
| Reason | String | Free text of the reason the call was made |
| ServiceName | String | Gateway service unique identifier |
| ProtocolVersion | String | Version of the headers |
| Timestamp | DateTime | Request timestamp |
3.2.2 SOAP Web Service
The SOAP Web service must have the following specifications:
- The web service must be WS-I Basic Profile 1.1 compliant
- The web service must generate a valid WSDL 1.1 document
- The web service must understand specific SOAP headers send by Gateway with namespace
- http://gateway.gov.cy/schema/header/v1 (see Gateway metadata)
3.2.3 DB Procedures
The Database store procedure must implement the following signature:
- inMsg: The request message in XML.
- GatewayHeader: The request Gateway metadata in XML
- outMsg: The response message in XML
The Backend system MUST configure one store procedure per database acting as an orchestrator and then call any other stored procedure.
The DB Connector currently supports the following databases:
- Oracle
- SQL Server.
The oracle store procedure signature should be as follow:
- inMsg: Type CLOB.
- GatewayHeader: Type CLOB
- outMsg : Type CLOB
The SQL Server store procedure signature should be as follow:
- inMsg: Type nvarchar(max).
- GatewayHeader: Type nvarchar(max)
- outMsg : Type nvarchar(max)
4 Outbound Message Specifications
The present section specifies the protocols and interfaces in order to submit synchronous or asynchronous request, asynchronous response and query messages between Government departments through the DIS Connector and the Government Gateway.
4.1 Supported Message Patterns
DIS Connector supports following message exchange:
- In the synchronous outbound exchange, the client application makes a synchronous call to the DIS Connector and waits for a business response message from the provider.
- In the asynchronous outbound exchange, the client application makes a synchronous call to the DIS Connector, triggering a long-running operation on the provider.
4.2 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}/api/v1.0
FQDN: A fully qualified domain name (FQDN) that identifies the connector host.
4.3 Synchronous Outbound Request
4.3.1 HTTP Request
To send a new outbound message, make an HTTP POST to the following resource URL.
Resource: https://{Base URL}/outbound/request/{provider}/{serviceName}
Each service in gateway is uniquely identified by the combination of Provider and ServiceName. These will be configured by the Gateway Team.
4.3.1.1 Authentication
HTTP request to REST API are protected with Basic authentication (Link). In short, you will use your department system account provided by the Gateway Team.
4.3.1.2 HTTP Headers
The following HTTP Headers may be provided.
4.3.1.2.1 X-TransactionID (optional)
Description: In case the message is related to another request. It will contain the correlation id of the related request
Format: String
4.3.1.2.2 X-Reason (optional)
Description: Free text of the reason the call was made Format: String
4.3.1.3 Payload
The payload must be a valid XML as specified by the provider of the API.
4.3.2 HTTP Response
4.3.2.1 HTTP Headers
4.3.2.1.1 X-RequestID
The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.
4.3.2.1.2 X-CorrelationID
This HTTP header is returned in case of a successful request. Contains the Message ID generated by Gateway.
4.3.2.2 Possible HTTP status Codes
| HTTP Status | Description |
|---|---|
| 200 OK | The request was successful and the response body contains the XML received from the department. |
| 401 UNAUTHORIZED | The supplied credentials, if any, are not sufficient to access the resource. |
| 400 BAD REQUEST | Empty request body or not valid XML. |
| 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. |
| 502 BAD GATEWAY | The server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: Communication Failure with the central Hub or the Hub with the DepartmentError response by the department that is not a valid business message response. |
4.3.2.3 Successful Response Format
When the HTTP Status Code is 200 OK then the response body contains a valid XML message as specified by the provider of the API.
4.3.2.4 Error Response Format
The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1”.
An error has the following properties:
| Property | Description |
|---|---|
| Description | Error Description |
| Number | Error Number |
4.4 Asynchronous Outbound Request
The client application makes a synchronous call to the Connector, triggering a long- running operation on the provider.
The connector responds synchronously as quickly as possible. It returns an HTTP 202 (Accepted) status code, acknowledging that the request has been received for processing.
The response header holds a location reference pointing to an endpoint that the client can check for the result of the long running operation.
4.4.1 HTTP Request
To send a new asynchronous outbound message, make an HTTP POST to the following resource URL.
Resource: https://{Base URL}/outbound/async/request/{provider}/{serviceName}
Each service in gateway is uniquely identified by the combination of Provider and ServiceName. These will be configured by the Gateway Team.
4.4.1.1 Authentication
HTTP request to this endpoint is protected with Basic authentication (Link). In short, you will use your department system account provided by the Gateway Team.
4.4.1.2 HTTP Headers
The following HTTP Headers may be provided.
4.4.1.2.1 X-TransactionID (optional)
Description: In case the message is related to another request. It will contain the correlation id of the related request
Format: String
4.4.1.2.2 X-Reason (optional)
Description: Free text of the reason the call was made Format: String
4.4.1.3 Payload
The payload must be a valid XML as specified by the provider of the API.
4.4.2 HTTP Response
4.4.2.1 HTTP Headers
4.4.2.1.1 X-RequestID
The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.
4.4.2.1.2 X-CorrelationID
Returned on http status 202 Accepted. Contains the Message ID generated by Gateway.
4.4.2.1.3 Location
Returned on http status 202 Accepted. A URL the client should poll for a response status. See section 4 of this document.
4.4.2.1.4 Retry-After
Returned on http status 202 Accepted. Indicates how long the client should wait before making a follow-up request. A non-negative integer indicating the seconds to delay.
4.4.2.2 Possible HTTP status Codes
| HTTP Status | Description |
|---|---|
| 202 ACCEPTED | The request was successful received for processing. |
| 401 UNAUTHORIZED | The supplied credentials, if any, are not sufficient to access the resource. |
| 400 BAD REQUEST | Empty request body or not valid XML. |
| 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. |
| 502 BAD GATEWAY | The server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: Communication Failure with the central Hub or the Hub with the DepartmentError response by the department that is not a valid business message response. |
4.4.2.3 Successful Response Format
When the HTTP Status Code is 202 ACCEPTED then the response body is empty.
4.4.2.4 Error Response Format
The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1”.
An error has the following properties:
| Property | Description |
|---|---|
| Description | Error Description |
| Number | Error Number |
4.5 Status Request for Asynchronous Outbound Request
The client application makes a synchronous call to the Connector, to receive the response for a long running operation initiated by an asynchronous outbound request.
4.5.1 HTTP Request
The client must send an HTTP GET request to the status endpoint.
The initial status endpoint was returned in the location header of the asynchronous outbound response.
4.5.2 HTTP Response
4.5.2.1 HTTP Headers
4.5.2.1.1 X-RequestID
The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.
4.5.2.1.2 X-CorrelationID
This HTTP header is returned in case of a HTTP status code 200 / 202. Contains the Message ID generated by Gateway.
4.5.2.1.3 Location
Returned on http status 202 Accepted. A URL the client should poll for a response status.
4.5.2.1.4 Retry-After
Returned on http status 202 Accepted. Indicates how long the client should wait before making a follow-up request. A non-negative integer indicating the seconds to delay.
4.5.2.2 Possible HTTP status Codes
| HTTP Status | Description |
|---|---|
| 200 OK | The request was successful and the response body contains the XML received from the department |
| 202 ACCEPTED | The request was successful received for processing. |
| 401 UNAUTHORIZED | The supplied credentials, if any, are not sufficient to access the resource. |
| 400 BAD REQUEST | Empty request body or not valid XML. |
| 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. |
| 502 BAD GATEWAY | The server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: Communication Failure with the central Hub or the Hub with the DepartmentError response by the department that is not a valid business message response. |
4.5.2.3 Successful Response Format
When the HTTP Status Code is 202 ACCEPTED then the response body is empty.
4.5.2.4 Error Response Format
The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1”.
An error has the following properties:
| Property | Description |
|---|---|
| Description | Error Description |
| Number | Error Number |
4.6 Asynchronous Outbound Response
The client application makes a synchronous call to the Connector, to return the result of an Asynchronous Inbound Request.
The connector responds synchronously as quickly as possible. It returns an HTTP 202 (ACCEPTED) status code, acknowledging that the response has been received.
4.6.1 HTTP Request
To send a new outbound response message, make an HTTP POST to the following resource URL.
Resource: https://{Base URL}/outbound/async/response/{provider}/{serviceName}/{CorrelationID}
Each service in gateway is uniquely identified by the combination of Provider and ServiceName. These will be configured by the Gateway Team.
The CorrelationID is the Message id generated by Gateway and was delivered with the asynchronous inbound request (see ” D3.3-Gateway DIS Interface Specifications-v2 / 3.1.1.1 Gateway Metadata”)
4.6.1.1 Authentication
HTTP request to this endpoint is protected with Basic authentication (Link). In short, you will use your department system account provided by the Gateway Team.
4.6.1.2 HTTP Headers
The following HTTP Headers may be provided.
4.6.1.2.1 X-TransactionID (optional)
Description: In case the message is related to another request. It will contain the correlation id of the related request
Format: String
4.6.1.3 Payload
The payload must be a valid XML as specified by the provider of the API.
4.6.2 HTTP Response
4.6.2.1 HTTP Headers
4.6.2.1.1 X-RequestID
The HTTP header is always returned. Contains the Message ID generated by the Connector. You may use this for troubleshooting.
4.6.2.1.2 X-CorrelationID
Returned on http status 202 Accepted. Contains the Message ID generated by Gateway.
4.6.2.2 Possible HTTP status Codes
| HTTP Status | Description |
|---|---|
| 202 ACCEPTED | The response was successful received for processing. |
| 401 UNAUTHORIZED | The supplied credentials, if any, are not sufficient to access the resource. |
| 400 BAD REQUEST | Empty request body or not valid XML. |
| 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. |
| 502 BAD GATEWAY | The server while acting as a gateway or proxy, received an invalid response from the upstream server. This error may receive due to: – Communication Failure with the central Hub or the Hub with the Department |
4.6.2.3 Successful Response Format
When the HTTP Status Code is 202 ACCEPTED then the response body is empty.
4.6.2.4 Error Response Format
The REST API will return an error in the HTTP response body when something goes wrong. In XML, these appear as <ConnectorOutboundErrorResponse> element with namespace “http://gateway.gov.cy/schema/error/v1”.
An error has the following properties:
| Property | Description |
|---|---|
| Description | Error Description |
| Number | Error Number |
