Support

The TNSadmin.com REST API

Introduction

REST API (Representational State Transfer Application Programming Interface or RESTful web service) is a web API implemented using HTTP and the principles of REST. It is a collection of resources, with four defined aspects:

Base URI (e.g. http://tnsadmin.com/api)
Internet media type of the data supported (JSON, XML, ...)
Set of operations using HTTP methods (GET, PUT, POST, or DELETE)
Hypertext driven

Source: https://en.wikipedia.org/wiki/Representational_state_transfer

Tools for the REST API Communication

The following examples use Linux tools - wget, curl, and Java tool: Apache Ant. You can also use Firefox REST API plugin for the simulations.

LIST (GET) Operations

You get a list of databases or one database connect string using the HTTP GET method and tools wget or curl. The examples show, how to get plain text connect string, XML or JSON format strings.

export TNADMIN_URL=http://127.0.0.1:8080
export TNSADMIN_USER=tnsadmin
export TNSADMIN_PASSW=tnsadmin
wget -S -q -O - ${TNADMIN_URL}/tnsnames.ora
wget -S -q -O - ${TNADMIN_URL}/tnsnames.ora?code=mydb
wget -S -q -O - ${TNADMIN_URL}/tnsnames.ora?id=MYDB.TNSADMIN.NET 2> /dev/null
wget -S -q --header "Accept: application/json" -O - ${TNADMIN_URL}/api/databases
wget -S -q --header "Accept: application/xml" -O - ${TNADMIN_URL}/api/databases
wget -S -q --header "Accept: application/json" -O - ${TNADMIN_URL}/api/databases/MYDB.TNSADMIN.NET
wget -S -q --header "Accept: application/xml" -O - ${TNADMIN_URL}/api/databases/MYDB
curl -i -H "Accept: application/json" ${TNADMIN_URL}/api/databases
curl -i -H "Accept: application/xml" ${TNADMIN_URL}/api/databases

Apache Ant can be used to automate various database update tasks (Java platform):

<?xml version="1.0" encoding="UTF-8" ?>
<project name="Connect to database" default="all" basedir=".">
<property name="db.code" value="MYDB" />
<property name="tnsadmin.url" value="http://127.0.0.1:8888/tnsnames.ora?code=${db.code}&type=jdbc" />
<property name="db.file" value="/tmp/db.txt" />

<target name="get.connect.and.run">
<!-- get database connect properties -->
<get src="${tnsadmin.url}" dest="${db.file}" />
<loadfile property="db.connect" srcFile="${db.file}" />
<delete file="${db.file}" />
<!-- use db.file property to connect to a database -->
...
</target>
</project>

INSERT (HTTP PUT)

Update operations require the authentication and authorization. The URI /api/secured is for this reason secured using BASIC authentication and requires administration role.
Let's create a XML input file (rest_sample1.xml) with 'id' element, which is unique.

<database>
  <id>mydb1.tnsadmin.net</id>
  <comment></comment>
  <connectString>
    (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=MYHOST)(PORT=1234)))
    (CONNECT_DATA=(SERVICE_NAME=MYSERVICE.TNSADMIN.NET)))
  </connectString>
  <jdbcConnectString>jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=
    (ADDRESS=(PROTOCOL=TCP)(HOST=MYHOST)(PORT=1234)))
    (CONNECT_DATA=(SERVICE_NAME=MYDB1.TNSADMIN.NET)))
  </jdbcConnectString>
  <jdbcLdapConnectString>jdbc:oracle:thin:@ldap://myldap.tnsadmin.net:12389/mydb1,cn=OracleContext,dc=tnsadmin,dc=net</jdbcLdapConnectString>
</database>

The following code creates new item (XML format is used here, content type must be specified):

curl -X PUT --data-binary @/home/myuser/rest_sample1.xml -u "${TNSADMIN_USER}:${TNSADMIN_PASSW}" -H "Content-Type: application/xml" ${TNADMIN_URL}/api/secured/database

UPDATE (HTTP POST) Operation

Update operation also contains 'id' specifier of the database. The sent XML can contain different 'id' value, if the item is about to be replaced. The JSON format is also supported.
Let's create other XML input file (rest_sample2.xml):

<database>
  <id>mydb.tnsadmin.net</id>
  <comment></comment>
  <connectString>
    (DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=MYHOST)(PORT=1234)))
    (CONNECT_DATA=(SERVICE_NAME=MYSERVICE.TNSADMIN.NET)))
  </connectString>
  <id>mydb.tnsadmin.net</id>
  <jdbcConnectString>jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)
    (HOST=MYHOST)(PORT=1234)))(CONNECT_DATA=(SERVICE_NAME=MYDB.TNSADMIN.NET)))
  </jdbcConnectString>
  <jdbcLdapConnectString>jdbc:oracle:thin:@ldap://myldap.tnsadmin.net:12389/mydb,cn=OracleContext,dc=tnsadmin,dc=net</jdbcLdapConnectString>
</database>

The following code updates existing item:

curl -X POST \
     --data-binary @/home/myuser/rest_sample2.xml \
     -u "${TNSADMIN_USER}:${TNSADMIN_PASSW}" \
     -H "Content-Type: application/xml" ${TNADMIN_URL}/api/secured/database/MYDB.TNSADMIN.NET

DELETE (HTTP DELETE) Operation

Delete operation contains 'id' specifier of the database. The following code deletes existing item:

curl -X DELETE \
     -u "${TNSADMIN_USER}:${TNSADMIN_PASSW}" \
     -H "Accept: application/xml" ${TNADMIN_URL}/api/secured/database/MYDB1.TNSADMIN.NET

Conclusion

REST API is an efficient method of getting the database connection parameters. It can be used for automating various enterprise tasks and solutions (deployment of connection pools, update of databases, configuration of JEE applications, etc.)