Skip to content

Quickstart

This guide allows new users with working experience in HCL Notes and HCL Domino to quickly get started with Domino REST API. These are the steps:

Downloading Domino REST API

Log in to HCL Software License & Download Portal link image or My HCLSoftware Portal link image and download Domino REST API.

Let's connect

We really like to hear from you!

Your opinion matters. Let us know all your:

  • questions
  • discussions
  • ideas
  • feedback

Join the OpenNTF Discord channel.

What's New

Check What's New to learn what's new in Domino REST API.

The Domino REST API schema

You will find a snapshot of the Domino REST API schemas here. The actual schema however resides on your Domino REST API server instance as OpenAPI specification. You can read and explore it directly with your own data.

A few phrases you should know

  • A database exposed on the API is referred to as a scope. The exposure happens through an entry in Domino REST API's configuration database by an administrator with Editor access there. The scope gets used in the URLs as ?dataSource=[scopename]. Scopes for databases are lowercase only.
  • The shape of data available is referred to as a schema. The schema is an json file in the design resources of the database. It gets created by a developer with Designer access to the NSF.

  • A Domino REST API Application is an OAuth compatible definition of a client_id and a client_secret as well as the list of permitted scopes.

  • A scope points to a schema that is contained in a database. A database can have multiple schemas for different use cases and a schema can be pointed to by more than one scope.

Pick the name of your scope wisely. It's the external name you share with others and thus hard to change without breaking external apps.

Let's get started

To get up and running quickly, you will need to:

  • Install Domino REST API on a Notes client or a Domino server.

  • Pick a database you want to work with. You could use demo.nsf.

  • Use the Domino REST API to create a schema REST access (if you dare, use Domino Designer).

  • Pick the forms and fields to expose.

  • Pick the views you want to be REST accessible.

  • Pick the agents. (Optional)

  • Use the Domino REST API to create a scope.

  • Try out the API.

You can use the built-in Swagger API, Postman and Curl, or the Admin UI. To help you, use one of the following tutorials. We have a curl based Domino REST API shell script for you to play with.

Tip

Make sure to complete the post installation steps to ensure proper operation.

Tutorials

OpenAPI

The Postman collection has sample interactions with the local sample Demo.nsf, go check it out.

Roles

  • Domino developer creates the schema that defines what data can be accessed in a nsf database.
  • Domino administrator creates and activates the scope that defines how the data can be accessed. Also creates (optional) OAuth compatible applications with client_id and client_secret properties.
  • VoltMX administrator configures Volt MX's foundry middleware to interact with Domino REST API using the foundry Domino REST API adapter
  • Application developer develops applications leveraging Domino REST API Endpoints, VoltMX services and front-end tools like VoltMX Iris, VSCode or any tools and framework of choice

Read more about them in Domino REST API roles.

Endpoints

Ensure your endpoints are secure. Bring up a browser and verify that you can hit these endpoints:

Endpoints Ports Details Webpages
Domino REST API Home Page 8880 Start page StartPage
Live Domino REST API 8880 Interact live with the API OpenAPI
Admin UI 8880 Login with an admin user. LocalDomainAdmin member Admin Login
Management API 8889 Access to the log and runtime info Server Info
Prometheus Metrics 8890 Performance info in Prometheus format. Protected with basic authentication (metrics/metrics) Performance Metris
Health check endpoint 8886 Server healthcheck endpoint as used by Kubernetes or Openshift
Auth 8880 The endpoint, [POST] http/s://${HOST}:8880/api/v1/auth, is the default end point to exchange Domino web credentials for a JWT access token. For example, use the token in Postman request headers as a Bearer authentication header. You also can use your own IdP to gain access tokens

What's next?

Based on your interest, start by exploring the following sections of this documentation: