Using REST services to connect to other runtimes

The XPages NoSQL Database service supports the IBM® XPages for Bluemix™ runtime but it can also connect and work with other runtimes.

About this task

To connect an XPages NoSQL Database service instance to another runtime, you use the REST API provided by the XPages NoSQL Database service for storing and retrieving data. The first step in this process is to enable REST services access to your database. Follow these steps to do this:

Procedure

  1. Open the database in Domino® Designer. For more information, see Connecting to the XPages NoSQL Database service from Domino® Designer found in the service documentation on the Bluemix™ site.
  2. In the Applications Navigator, click Application Configuration > Application Properties to open the Application Properties editor.
  3. In the Application Properties editor, click the Advanced tab.
  4. In the Features section, select Views and documents from the Allow Domino Data Service menu.
  5. Click Save.
  6. To enable access for the View that you want to expose through the REST API, double-click the view in the Views section of the Applications Navigator.
  7. Right-click on the editor-pane and choose View Properties from the menu.
    The View Properties dialog box appears.
  8. In the View Properties dialog box, click the Advanced tab.
  9. In the Web Access section, enable the Allow Domino Data Service operations option by clicking the check-box.
  10. Close the View Properties dialog and save the View. Repeat steps 6-10 for each View that you want to expose through the REST API.

Example

Now that you have enabled REST API access for you database, you can use the REST API provided by the Service to parse the VCAP_SERVICES environment variable. The example that follows shows you how to retrieve view-specific data that you might want to access via the other runtime.

The VCAP_SERVICES environment variable supplies the connection information and credentials to access a bound XPages NoSQL Database service from any runtime. For example, given the following VCAP_SERVICES environment variable:

{
   "XPagesData": [
      {
         "name": "myXPagesDB-XPagesData",
         "label": "XPagesData",
         "plan": "xpages-data-free",
         "credentials": {
            "apppath": "bluemix/user/dev/data.nsf",
            "username": "xxxxxx,
            "host": "123.123.123.123",
            "rootdir": "bluemix/user/dev/",
            "servername": "CN=server_name/O=Bluemix",
            "password": "xxxxxx",
         }
      }
   ]
}

With an application running in Bluemix, you can retrieve a View that is called "myview" from this database. To do this, send a GET request to https://123.123.123.123/bluemix/user/dev/data.nsf/api/data/collections/name/myview.

The service responds with a 200 OK response (the request has succeeded) that contains the View entries in JSON format.

Note: If you are testing your application locally, outside of Bluemix, or sending test requests via a web browser, you will need to send the GET request to a slightly different URL. For example, when using the Dallas Bluemix server, you would use: https://xpages-domino.ng.bluemix.net/bluemix/user/dev/data.nsf/api/data/collections/name/myview. To find the correct hostname to use for local testing, consult the Bluemix Service Dashboard page where there is a value displayed called hostname (for example, xpages-domino.ng.bluemix.net).
Query parameters can be added to the request URI for operations such as searching and sorting.
Note: The Database Collection resource API is unavailable in this Bluemix™ service.

Providing security for REST requests

About this task

For security, all REST requests must be sent by HTTPS; HTTP is not enabled. You can require authentication by disabling anonymous access. When anonymous access is disabled, each REST request must contain a valid authorization header.

For credentials, use the user name and password that is supplied by the VCAP_SERVICES environment variable. To disable anonymous access, modify the Access Control List for the database with the following steps:

Procedure

  1. Open the database in Domino® Designer. For more information, see Connecting to the XPages NoSQL Database service from Domino® Designer found in the service documentation on the Bluemix™ site.
  2. In the Applications Navigator, right-click on the root of the application and select Application > Access Control from the menu.
  3. The Access Control List dialog box appears.
    This dialog controls which users can access the database and the access level of those users.
  4. If there is an Anonymous entry in the list, select it and then select No Access from the Access menu.
    If there is no Anonymous entry, no action is required.
  5. Select OK to save and close the dialog.