Core, Principal, and Query REST APIs

As of nevisIDM 2.69, a new set of REST APIs is available to simplify integrations with nevisIDM. Currently the following APIs are provided:

• Core: Provides access to the nevisIDM entities, like users, profiles, passwords or applications. In most cases, you use this API.
• Principal: Provides information about the currently logged-in user.
• Query: When indexing is enabled, allows querying of nevisIDM objects using a REST API, see Query REST Service for details.

All the REST APIs follow a resource-based approach and return JSON documents. API authentication requires a valid SecToken or client certificate, except when there is a nevisProxy configured in front of the API to provide alternative forms of authentication.

Currently the REST APIs may not cover all requested functionality. However, the scope of the APIs will be extended over time.

tip

For more information about available API calls, attributes and the corresponding version of nevisIDM, refer to the chapters: nevisIDM REST API documentation and Query REST Service.

Versioning and support

The nevisIDM version defines which resources, attributes and REST API calls are available. The scope of the APIs are extended over time, newer versions of nevisIDM usually provide additional or new resources in the REST API.

tip

To find out which resources and actions are available in your nevisIDM version, refer to the chapter "Query REST Service", or visit the separately zipped API documentation among the nevisIDM documents on Nevis Portal.

The version mentioned in the path of the REST API (for example, "v1" in /nevisidm/api/core/v1/users) defines the API baseline and forward compatibility. Newer versions of nevisIDM are compatible in that:

• they will not intentionally break existing API calls, resources or attributes;
• new and additional attributes might be returned;
• new and additional resources might be available.

Breaking changes

When breaking changes are introduced, either in the paths, requests or responses of the API, the version of the API is increased. This automatically marks the previous version as deprecated.

Deprecated versions

There is at most only one deprecated version. The deprecation period lasts until the next new breaking change or one year. Do not use deprecated versions in new projects.

Available REST API versions

Each of the new REST APIs is versioned separately. The next table lists the available REST API endpoints and baseline.

API	Endpoint	API baseline	Deprecated API baseline	Since
core	/nevisidm/api/core/v1	v1	none	2.69.x
principal	/nevisidm/api/principal/v1	v1	none	2.69.x
query	/nevisidm/api/query/v1	v1	none	2.67.x
auth	/nevisidm/api/auth/v1	v1	none	2.78.x
notification	/nevisidm/api/notification/v1	v1	none	2.79.x