What you need to know about the HCL Domino REST API (Part Three)

In parts one and two of the Domino Rest API blog series, we discussed how to install and configure the Domino REST API on your Domino server. In this article you will learn how to create the components that allow external applications to securely access Domino applications, their data and design elements.

What are Schemas, Scopes and OAuth Apps?

By default, no databases are available through the Domino REST API. You decide what Domino databases you want to enable. And, for those databases you can both select specific design elements and define what actions are allowed. This is called exposing the Domino application. Exposing a Domino application is a shared activity between Administrators and Developers. As shown in the following picture, the Developer creates the schema, and the Administrator enables the schema and creates the scope and OAuth application.

Schema - The design elements made available are referred to as a schema. The schema is a JSON file of specified design resources of the database. For Domino databases, this includes forms, their fields, views and agents. Creating and updating a schema requires Designer access to the NSF. Schemas can be created using the Domino REST API, the Domino REST API GUI (Admin UI) or Domino Designer editing the schema JSON file.

This creates the Alias. You can use this to access the database via the Domino REST API. One NSF can be available under more than one alias, such as with different security settings or different design elements defined.

Scope - Scopes define to whom a schema is exposed and specify the maximum allowed access when using the schema. The Domino Administrator uses a Domino application’s defined schema to create a scope, which is then stored in the Domino Keep Configuration, keepconfig.nsf, database. Those that create and update scopes require Editor access to keepconfig.nsf. When creating a scope, the Administrator defines the allowable maximum access when accessed through DRAPI. However, this does not change the ACL and it does not override the ACL. For example, if a user has Reader access to a database and the maximum allowed access is Editor, the user will maintain Reader access.

Application Management - OAuth – Depending on the use case, this may be considered an optional step. Domino REST API offers an OAuth/OIDC controlled access to be used by external systems, accomplished by defining the application using the scope and the external system’s callback URL. The resulting document is stored in the Domino Keep Configuration, keepconfig.nsf, database. When you use the Admin UI to create an application, an Application ID and Application Secret are generated. The external system will use these when accessing the Domino REST API using OAuth.

Domino REST API GUI (Admin UI)

The Admin UI provides an easy-to-use interface for creating and managing schemas, scopes and applications for Domino applications to be accessible via DRAPI. It is accessed using a web browser and the data port, 8880. For a Domino server, the url is the server’s hostname followed by the port of 8880, for example https://rock.adventure.com:8880.

1 . Using a web browser, go to http://serverhostname:8880 or http://127.0.0.1:8880

2 . Click Configuration

3 . Enter your user name and Internet password as per your person document in the Domino Directory

4 . Click [LOG IN]

The Domino REST API Admin UI page appears.

Let’s see how schemas, scopes and OAuth applications are created using the Admin UI.

Note: The follow steps and screenshots were created using DRAPI 1.0.9 on a Domino V14.0 server. If you are using a different version of DRAPI, you may notice some differences, but the base concepts remain the same.

Creating a Schema

1. On the left hand navigator bar click the  icon

2. Click [+ Add Schema]

3. Click Create Schema

Note: The option to Import Schema is explained later in this article.

4. For the dialog box that appears click the dropdown for the Database field to select the database

5. Click the dropdown next to the Icon to change the picture (optional)

6. For Schema Name, enter a name that represents the schema. The schema name is all one word and must be unique, meaning no other schemas defined on a particular Domino server will have the same value.

7. For Schema Description, enter a description

8. Formula Engine remains Domino

9. Click Save Schema to save

10. To see the newly created schema’s card click the toggle switch “Only show schemas configured with scopes” to Off

11. Click the card

First, we will expose the Marketing form.

12. Click Active to add the Marketing form to the schema

13. Click the Edit icon  to the left of the Marketing form

14. On the left hand side click the + icon to Add all fields to the schema

15. Click the FullName field. Note the ability to change the Access setting

16. Click Save

Note: The Mode Formula Settings section has options that further define what can be done through the Domino REST API. For example, by default Formula for Delete Access is @False, which means deletions are not allowed. Changing the value to @True, allows document deletions.

Note: For the above screenshot, the upper right-hand area has buttons named [Clone Mode] and [+Add Mode]. Form modes are a configuration used to manage access to documents and their data. Depending on the use case, multiple modes can be configured per form to provide different access based on the end point. The Admin UI lists four modes that provide a special purpose - default, dql, odata and raw.

17. At the top click the name of the schema

18. Click Database Views

19. For the ($All) view click Active

20. Click the Edit icon  to the left of ($All)

21. Click +Add All to add all view columns to the schema

22. Click Save

23. Click Source – Text Mode. This is the schema represented in JSON

This same information is stored as a Resource File and part of the design of the Domino NSF. Using the Domino Designer client you can review this file by going to Resources – Files.

Note: As previously mentioned, the schema is generally created by the Domino application developer, and for most organizations this is performed in a development environment. Developers can export the schema using the Domino Designer client or the REST API Admin UI. The Export and Import Schema buttons in the REST API Admin UI are intended to be used as part of the application’s promotion/deployment process. This means the application developer will create and export the schema using the Export button available on the schema’s Source page, typically performed in a separate development environment. The exported schema is saved as a JSON file. The developer will provide the administrator with this JSON file. Then the administrator will create a new schema in the respective database by using the Import Schema button and selecting the JSON file.

Creating the Scope

Now that we have a schema, we can create a scope.

1. Return to the Domino REST API Admin UI open in the web browser
2. In the upper left-hand area click Overview
3. On the left-hand navigator click the icon 
4. Click [+ Add Scope]
5. On the right-hand side of the dialog box, enter/select the Scope Name, Description, Domino Server, Maximum Access Level and Scope Icon
6. On the right-hand side of the dialog box, enter/select the Scope Name, Description, Domino Server, Maximum Access Level and Scope Icon
7. Click the [Add] button

Note: Maximum Access Level is regarding access through DRAPI. It does not update the database’s ACL. The user’s access defined in the Domino database ACL will not be exceeded. For example, if the user is defined in the ACL as a Reader and the scope’s maximum access is Editor, the user will not be able to create documents through DRAPI.

You will now see a card added for the Scope. Additionally, a document was created in the Domino Keep Configuration, keepconfig.nsf, database.

1. Open the Domino Administrator client to the server where DRAPI is installed
2. Select the Files tab
3. Open the Domino Keep Configuration, keepconfig.nsf, database
4. Select Active - Databases
5. Open the document with the same scope name

Creating an Application

As a final step in making the Domino database available through DRAPI, create an application that can be accessed from an external application using OAuth.

Depending on the use case of a database, creating an application may or may not be necessary as just the scope and schema may be sufficient.

1. Return to the Domino REST API Admin UI open in the web browser

2. For the left-hand navigator press the  icon 

3. Click [+ Add Application]

4. For the Add New Application dialog box, enter/select the Application Name, Description, Callback URL, Startup Page, Scope, Contacts and Icon

5. Click the [Add] button

Note: The callback url will be provided by the external application that will be accessing Domino through DRAPI, which is the redirect after OAuth authentication.

Note: After selecting the Scope from the dropdown menu click the + button

You will see a card for the Application now displays.

Note the App Id automatically generated. This is what is provided to the external application that will access the Domino application through DRAPI. Additionally, you need to generate an Application Secret.

6. For the Application Card mouse over the upper right-hand side and a set of icons will appear

7. Click the first icon, which reads Generate Application Secret

You will supply the Application Id and Application Secret to the external application that will be accessing the Demo database through DRAPI. And, no, you do not have to type the values out, simply click on the Id and Secret to copy the values to your clipboard.

Additionally, a document was created in the Domino Keep Configuration, keepconfig.nsf, database.

8. Open the Domino Administrator client to the server where DRAPI is installed

9. Select the Files tab

10. Open the Domino Keep Configuration, keepconfig.nsf, database

11. Select Active – Applications

12. Open the document with the same application name

I hope you have enjoyed this blog series, and it helps you install, configure and manage the Domino REST API on your Domino servers. Reach out with any questions you may have.