Validating server connections
Validating your server connections with REST endpoints is a simple way to test that your application can access databases and other sources of data. In Open Liberty, the features in your server configuration enable REST endpoints that you can use to view the server configuration and validate server connections to resources, such as databases.
By enabling the Admin REST Connector feature, you can use the config
REST endpoint to view the server configuration. If you also enable the JDBC, JCA, Cloudant Integration, or JMS features with the Admin REST Connector feature, you can use the validation
REST endpoint to validate connections to certain types of resources. If any of the MicroProfile OpenAPI features are enabled, you can view dynamically generated OpenAPI documents for the config
and validation
REST endpoints. The following table provides the config
and validation
REST endpoint paths for the Admin REST Connector, JDBC, Cloudant Integration, JCA, JMS, and OpenAPI features.
Feature | REST endpoint paths |
---|---|
Admin REST Connector | /config |
JDBC | /validation/dataSource |
JCA | /validation/connectionFactory |
JMS | /validation/jmsconnectionFactory |
Cloudant Integration | /validation/cloudantDatabase |
MicroProfile Open API | /openapi/platform/config |
You can also use Server Config tool in the Liberty Admin Center to test connections to JDBC, JCA, JMS, and Cloudant resources. For more information, see Manage Open Liberty with Admin Center.
Before you begin
To access the REST endpoints, you must authenticate with the Open Liberty server. Ensure that you have a minimum of reader-role
access to the config
REST endpoint and administrator-role
access to the validation
REST endpoint. You can use any Open Liberty supported user registry to set up secure access. However, the following examples include either QuickStart security or a basic user registry with the Application Security feature enabled.
Viewing server configuration
To view your server configuration, specify the proper config
REST endpoint URL. The config
REST endpoint URL for any server configuration element is specified with the base URL, the REST endpoint path, the server configuration element name, and its unique ID (UID). In the following example, the configElementName
variable specifies the server configuration element and the uid
variable specifies the UID.
https://localhost:9443/ibm/api/config/configElementName/uid
The https://localhost:9443/ibm/api
base URL is set by default. To list all instances of a specific configuration element name in the output of the config
REST endpoint, omit the uid
variable from the REST endpoint URL. To list every instance of all the server.xml
file configuration elements in the output of the config
REST endpoint, you must also omit the configuration element name from the REST endpoint URL. The output also includes any configuration files and any default instances that are defined by the features of the server.
Validating a connection to a database
When you use the config
REST endpoint URL to view your server configuration, you can use the generated output to specify the validation
REST endpoint URL. The output from the config
REST endpoint URL provides the input URL for the validation
endpoint. When the dataSource
element is specified in the config
REST endpoint URL, this validation
REST endpoint URL validates connections to resources that are configured with the dataSource
element. The value of the id
attribute in the dataSource
element is the UID that is specified in the config
REST endpoint URL.
The following example shows a server.xml
file with the REST Connector and JDBC features enabled and a Derby database that is configured as the default data source.
<server>
<featureManager>
<feature>appSecurity-2.0</feature>
<feature>restConnector-2.0</feature>
<feature>jdbc-4.2</feature>
</featureManager>
<keyStore id="defaultKeyStore" password="Liberty"/>
<quickStartSecurity userName="blogAdmin" userPassword="blogAdminPassword"/>
<library id="derby">
<file name="${server.config.dir}/derby/derby.jar"/>
</library>
<dataSource id="DefaultDataSource">
<jdbcDriver libraryRef="derby"/>
<properties.derby.embedded databaseName="memory:defaultdb" createDatabase="create" user="dbuser" password="dbpass"/>
</dataSource>
...
</server>
To validate the connection to this database, find the validation
REST endpoint path by using the https://localhost:9443/ibm/api/config/dataSource/DefaultDataSource
REST endpoint URL to view the datasource
element configuration output. In the output, the /ibm/api/validation/dataSource/DefaultDataSource
value of the api
field specifies the validation
REST endpoint path, as shown in the following example.
{
"configElementName": "dataSource",
"uid": "DefaultDataSource",
"id": "DefaultDataSource",
"beginTranForResultSetScrollingAPIs": true,
"beginTranForVendorAPIs": true,
"connectionSharing": "MatchOriginalRequest",
"enableConnectionCasting": false,
"jdbcDriverRef": [
{
"configElementName": "jdbcDriver",
"uid": "dataSource[DefaultDataSource]/jdbcDriver[default-0]",
"libraryRef": [
{
"configElementName": "library",
"uid": "derby",
"id": "derby",
"apiTypeVisibility": "spec,ibm-api,api,stable",
"fileRef": [
{
"configElementName": "file",
"uid": "library[derby]/file[default-0]",
"name": "/opt/ol/wlp/usr/custom.repository"
}
]
}
]
}
],
"statementCacheSize": 10,
"syncQueryTimeoutWithTransactionTimeout": "false",
"transactional": "true",
"properties.derby.embedded": [
{
"createDatabase": "create",
"databaseName": "memory:defaultdb",
"password": "******",
"user": "dbuser"
}
],
"api": [
"/ibm/api/validation/dataSource/DefaultDataSource"
]
}
Append the validation
REST endpoint path to the base URL of the server to specify the https://localhost:9443/ibm/api/validation/dataSource/DefaultDataSource
REST endpoint URL. This URL generates the output for the specified DefaultDataSource
element. Examine the output of the validation
REST endpoint for success or failure. When the connection to the data source works properly, a success message appears, as shown in the following example.
{
"uid": "DefaultDataSource",
"id": "DefaultDataSource",
"successful": true,
"info": {
"databaseProductName": "Apache Derby",
"databaseProductVersion": "10.11.1.1 - (1616546)",
"jdbcDriverName": "Apache Derby Embedded JDBC Driver",
"jdbcDriverVersion": "10.11.1.1 - (1616546)",
"schema": "DBUSER",
"user": "dbuser"
}
}
If the connection to the data source has a problem, a failure message displays, and details about the failure are displayed. In the following example, a data source is configured in a server.xml
file that uses container authentication and an authentication alias.
<dataSource containerAuthDataRef="db2authAlias" id="myDS" jndiName="jdbc/db2DS">
<jdbcDriver libraryRef="db2Lib"/>
<properties.db2.jcc databaseName="testdb2" portNumber="50000" serverName="localhost" />
</dataSource>
<authData id="db2authAlias" password="db2pass" user="db2inst1"/>
If you attempt to validate the connection to this data source with the https://localhost:9443/ibm/api/validation/dataSource/myDS
REST endpoint URL without providing credentials, the generated output indicates a failure and an exception stack is displayed, as shown in the following example.
{
"uid": "myDS",
"id": "myDS",
"jndiName": "jdbc/db2DS",
"successful": false,
"failure": {
"sqlState": "42815",
"errorCode": "-4461",
"class": "java.sql.SQLNonTransientException",
"message": "[jcc][t4][10205][11234][4.22.29] Null userid is not supported. ERRORCODE=-4461, SQLSTATE=42815 DSRA0010E: SQL State = 42815, Error Code = -4,461",
"stack": [
"com.ibm.db2.jcc.am.ld.a(ld.java:810)",
]
}
}
To correct this failure, provide credentials for validation when the data source is configured to use authentication. You can validate a data source with container and application authentication by including the auth
parameter in the REST endpoint URL. If container authentication and an authentication alias are configured for your server, append the auth
and authAlias
parameters to the validation
REST endpoint URL by using the following HTTP query parameter syntax.
https://localhost:9443/ibm/api/validation/dataSource/myDS?auth=container&authAlias=db2authAlias
If the data source or connection factory that is validated uses application authentication, you must set the value of the authentication parameter to application
. You can use the X-Validation-User and X-Validation-Password HTTP headers to specify a username and password when you are not using container authentication to validate the connection to the database. You set HTTP headers by using either browser plug-ins or HTTP tools. For more information, see HTTP headers.
In addition to relational databases, Cloudant database connections can also be validated. For more information, see the Cloudant Integration feature.
Validating JMS and JCA connection factories
When you enable the JMS or JCA feature with the Admin REST Connector feature, you can use a validation
REST endpoint to validate connection factories. The following example shows a JCA connection factory configuration with the REST Connector and JCA features enabled in the server.xml
file.
<server>
<featureManager>
<feature>appSecurity-2.0</feature>
<feature>restConnector-2.0</feature>
<feature>jca-1.7</feature>
</featureManager>
<keyStore id="defaultKeyStore" password="Liberty"/>
<basicRegistry>
<user name="blogAdmin" password="blogAdminPwd" />
<user name="blogReader" password="blogReaderPwd" />
<user name="blogUser" password="blogUserPwd" />
</basicRegistry>
<administrator-role>
<user>blogAdmin</user>
</administrator-role>
<reader-role>
<user>blogReader</user>
</reader-role>
<authData id="auth2" user="containerAuthUser2" password="2containerAuthUser"/>
<connectionFactory id="cf1" jndiName="eis/cf1">
<containerAuthData user="containerAuthUser1" password="1containerAuthUser"/>
<properties.TestValidationAdapter.ConnectionFactory hostName="myhost.openliberty.io" portNumber="9876"/>
</connectionFactory>
...
</server>
The id
attribute in the connectionFactory
element specifies a unique cf1
value. You can use the unique value as the uid
parameter of the config
REST endpoint URL to view the output of the connectionFactory
element configuration.
By examining the output from the https://localhost:9443/ibm/api/config/connectionFactory/cf1
REST endpoint URL, you can find the validation
REST endpoint path in the api
field. In the following example, the api
field specifies the /ibm/api/validation/connectionFactory/cf1
value.
{
"configElementName": "connectionFactory",
"uid": "cf1",
"id": "cf1",
"jndiName": "eis/cf1",
"containerAuthDataRef": {
"configElementName": "containerAuthData",
"uid": "connectionFactory[cf1]/containerAuthData[default-0]",
"password": "******",
"user": "containerAuthUser1"
},
"properties.TestValidationAdapter.ConnectionFactory": {
"hostName": "myhost.openliberty.io",
"password": "******",
"portNumber": 9876,
"userName": "DefaultUserName"
},
"api": [
"/ibm/api/validation/connectionFactory/cf1"
]
}
Append the validation
REST endpoint path to the base server URL to specify the https://localhost:9443/ibm/api/validation/connectionFactory/cf1
endpoint URL. The auth
and authAlias
parameters are not specified in the validation
REST endpoint URL. You don’t need to specify the parameters because the containerAuthData
element in the server configuration specifies the credentials that are used for authentication if container authentication is used without providing credentials.
Examine the output of the https://localhost:9443/ibm/api/validation/connectionFactory/cf1
REST endpoint URL to determine the success or failure of the connection. If the validation of the connection factory is successful, a success message appears, as shown in the following example.
{
"uid": "cf1",
"id": "cf1",
"jndiName": "eis/cf1",
"successful": true,
"info": {
"resourceAdapterName": "TestValidationAdapter",
"resourceAdapterVersion": "28.45.53",
"resourceAdapterJCASupport": "1.7",
"resourceAdapterVendor": "OpenLiberty",
"resourceAdapterDescription": "This tiny resource adapter doesn't do much at all.",
"eisProductName": "TestValidationEIS",
"eisProductVersion": "33.56.65",
"user": "containerAuthUser1"
}
}
Viewing API documentation
When you enable any MicroProfile OpenAPI feature, you can view API documentation that helps you understand how REST APIs validate server connections with the config
and validation
REST endpoints. The API documentation provides descriptions of the REST endpoints and any other details that you need to use the REST API. You can generate this documentation in either YAML or JSON format by specifying the format
parameter in the REST endpoint URL. If you do not specify the format
parameter, the documentation is generated in YAML format by default. To generate the API document for the validation
REST endpoint in YAML format, specify the following validation
endpoint URL.
https://localhost:9443/openapi/platform/validation
To generate the API document for the config
REST endpoint in JSON format, specify the following config
endpoint URL.
https://localhost:9443/openapi/platform/config?format=json
For more information, see API documentation with OpenAPI.