Chat now with support
Chat with Support

Identity Manager 8.1.4 - API Designer User and Development Guide

API Designer Basic principles of API development Examples and help – Software Development Kit Quick start – Creating an API Working with the API Designer
Starting the API Designer Project types User interface Global settings Database objects Labeling changes Find and replace Multilingual captions Managing database queries Managing tabs Managing layouts Displaying the change history (command list) Bookmarks Compiling an API Managing versions (compilation branches) Testing an API Linking C# projects to the API Designer
API projects API files API Server ImxClient command line program

API Designer

The API Designer allows you to create, record, compile, and publish a REST API (Representational State Transfer Application Programming Interface) in the quickest way possible. This API is based on the OpenAPI Specification and the One Identity Manager database model.

The main benefits of API Designer include:

  • Offers easy and fast operation.

  • The finished API "understands" the One Identity Manager database model.

  • Modifications to the API are transparent.

  • Supports the principles of good API design.

  • OpenAPI support: APIs that you create using the API Designer are based on the OpenAPI specification standard. This allows you to make use of other tools, including:

    • Swagger: Use Swagger to create code, documentation, and test cases.
    • Postman: Use Postman to test the various methods of your API.

Basic principles of API development

The main components of an API created using the API Designer are files and projects.

Basic information on API files:

  • Use API files to define API methods for sending data to the application or to querying data from the application.

  • An API file can belong to more than one project.

  • Because the API Server is stateless, save the API methods that you specify in API files, without a client specific state.
    For example, you cannot, therefore, define global variables or store session object status data. When the API Server processes are restarted, these values are not restored.

  • Use asynchronous code for defining API methods. This supports more efficient usage of server resources and improves performance of the system under load. The methods of the API and the underlying object model convert this asynchronousity using the Task-based Asynchronous Pattern (TAP). For more information about TAP, see

  • Do not use the HttpContext.Current method when you define API methods. You can query the current HTTP requirements with the QBM.CompositionApi.ApiManager.Context.Current static method.

The basics of API projects:

  • API projects combine multiple API files into logical sections. The API project includes the configuration.

Basic information about the API Server:

  • The API server is implemented using the Owin Platform (see

  • Access to current HTTP requirements is not supported by ASP.NET APIs.

  • After enabling routes, you cannot change the definition objects anymore.

Related topics

Guidelines and conventions

In this chapter, you will find general policies and conventions, which you must take into account when you create an API.

Related topics

Handling of API Server queries

In this section, you will find information about handling queries that are sent to the API server.


When a query is sent to the API Server, there is a test to ascertain the success of the primary and, possibly, secondary login in the session for the current project (see Authentication).

NOTE: This test is not done if the API method used by the query is marked as AllowUnauthenticated.

The imx-session-<API project name> cookie is evaluated to allocate the current session.

If a cookie is passed that cannot be associated with an active session in the current process, the security token in the cookie is used to set up a new session (see Session status and security tokens).

If there is no primary login, the API Server tries to establish a database connection through one of the enabled single sign-on authentication modules.

If login cannot be carried out, the process is canceled and the HTTP error code 500 is passed to the client (see Response codes).

Authorizing method access

The API Server checks whether the currently logged in user is authorized to run the method. If the user does not have the required permissions, the process is canceled and the HTTP error code 500 is passed to the client (see Response codes).

Validating the query

The API Server calls the validators stored with the API method one by one. If one fails, the process is canceled and the HTTP error code 400 is passed to the client (see Response codes).

Processing queries (for entity methods)
  • GET (for loading entities)
    • Determines the WHERE clause with internal and external filters

    • Loads data from the database

    • Enriches entities with calculated columns

  • Entities in delayed logic mode can be changed with a POST query or deleted with a DELETE query. Entities in this mode are stateless and do not occupy resources on the server after the query has been processed.
    Supported HTTP methods:

    • GET (for loading entities)

    • POST (for changing entities)

    • DELETE (for deleting entities)

  • Interactive entities must be created once with a PUT query and after that they obtain their own ID. Use the ID in subsequent queries (POST or DELETE).

    Supported HTTP methods:

    • PUT (for creating interactive entities)

    • POST (for changing interactive entities)

    • DELETE (for deleting interactive entities)

Self Service Tools
Knowledge Base
Notifications & Alerts
Product Support
Software Downloads
Technical Documentation
User Forums
Video Tutorials
RSS Feed
Contact Us
Licensing Assistance
Technical Support
View All
Related Documents

The document was helpful.

Select Rating

I easily found the information I needed.

Select Rating