Tutorial

The tutorial will walk you through the first steps getting familiar with the KEEP API. For the purpose of this tutorial we presume you are using a local installation (using your Notes client) and not a Domino server side installation.

On it’s first run the Keep API creates a database keepconfig.nsf with the alias name keepconfig. It contains a database configuration demo pointing to Demo.nsf, you can download it in Resources.

A local installation of KEEP uses local user accounts stored in the keepconfig.nsf. To be able to use the api you need to enable the User John Doe using your Notes client:

John Doe

His password is password.

Concepts

Read them, it makes it easier to understand

KEEP Overview

  • The Keep API requires a JWT Token as authorization. In a production environment that Token most likely gets provided by an external provider (KeyCloack, Active Directory, LDAP etc.). To simplify your life, KEEP can exchange a username/password for an JWT Token using the /auth endpoint. The Admin UI currently uses that functionality
  • Databases on KEEP are addressed using a case sensitive alias to decouple the database file name from the API name. So when you move databases around you don’t break your external consumers
  • Only databases with an Alias, specified in a configuration document in KeepConfig.nsf are available in the KEEP API. The configuration entries are maintained through API calls or the Admin UI (that uses those calls)
  • Inside the configuration we specify what forms are available in the API. Only documents with the forms specified will load. However view data will load regardless of the form name
  • By default all views are accessible, we can, however, specify which ones to suppress
  • One database can be exposed with more than one alias and different configuration settings
  • We have “Application Server Access” (we call it short: applications) where we specify a clientId and a clientSecret as well as the participating databases. This allows us to give an application server more access than just a browser
  • We support browser based apps, that are hosted on a static http server (The Admin UI is such an example)
  • Domino’s security model is preserved. When a user doesn’t have access to a database or document KEEP doesn’t bypass it. However we extend that model with Document “Modes” where access to fields is limited by the mode a document is in

What’s next

We will create a new entry for a database, so we can access its content via the KEEP API. Let’s get going!