Accessing KEEP APIs using Postman

For an introduction into Postman, including setting up Postman with the required collections and environments, check the Postman Tool page.

Collections, Environments and Tests

Requests are grouped into Collections. Our collections correspond to the OpenAPI specifications we have set up. Each collection has folders corresponding to the tags in the OpenAPI specification. Within each folder are requests corresponding to the endpoints available in the OpenAPI specifications.

Every test uses environment variables, at the very least for the URL. This means you need to choose the appropriate environment. Environments can be duplicated, if you want to connect to a different Keep environment.

Tests are used for two purposes: to validate the response and assign portions of the response to environment variables. This is most commonly done on POST or PUT requests. A good example is in the “Admin Login” request. There the bearer token is extracted from the response and assigned to the AUTH_KEY environment variable.

Auth Test

All requests provide full sample body content. There are not requests covering all potential querystring parameters. For example, getting a view can include start and count parameters.

Authentication

Every request in Keep requires passing a JWT token. This is retrieved by using the “Admin Login” request in the “authentication” folder. This is added into all collections. If you open up the Body section, you will see this:

Auth Example

The username and password set up by default in the environment are “John Doe” and “password”, which will work if you are running against a Notes Client as covered in the startup guide. For authenticating against a Keep installation on a Domino server, change the values in the environment accordingly.

Domino Keep API

authentication Folder

This folder contains requests for logging in and creating local users. Local users are intended for testing authentication against Notes Client databases, in the same way as you authenticate to a Domino server. When initially created, users are inactive. To use the users, you will need to:
- Create the user.
- Update the user, setting “isActive” to true.
- Add the user to the ACL of a database - this can be done via Notes Client or using endpoints for managing access are in the Domino Keep Admin API collection.

A db query parameter is not required for these requests.

adminServer Folder

This folder contains requests for administering the Keep HTTP server, typically running on port 8889. These can be used for troubleshooting, correctly shutting down Keep and reloading Keep.

admin Folder

This folder contains requests used by the Keep Admin GUI - adding a Keep Database, Keep Database form modes and Keep Applications for more secure server-to-server communication with a Keep Database.

A db query parameter is not required for these requests.

design Folder

This folder contains requests for creating NSFs, views and forms and managing DXL (Domino XML). The db query parameter is either a Keep database or a database filepath.

data Folder

This folder contains requests for interacting with data in a database. This allows you to:
- get a list of Keep databases available for query.
- get lists of documents in a database.
- interact with documents in a database.
- query documents in a database.
- interact with attachments in a database.

The Demo database does not contain documents with attachments. So it is recommended that you create a database from the “StdR10TeamRoom” template (setting the ACL accordingly), create a document in it and add an attachment.

code Folder

This folder contains requests for interacting with agents and running programmatic code. These are still in development.

jwt Folder

This folder contains a request that will only work if you have a JWT provider set up.

odata Folder

This folder contains requests used by Excel or other applications that are designed to work with ODATA endpoints.

metrics Request

This request gets Keep and Vert.x metrics in a format that can be used by Prometheus.

Domino Keep Admin API

authentication Folder

This folder contains duplicates the request to authenticate to Keep.

database Folder

This folder contains requests for managing ACL entries and ACL roles, for access to an NSF.

user Folder

This folder contains requests for managing groups in Domino Directories.

Domino Keep PIM API

T.B.C.

Domino Keep Experimental API

T.B.C.