Chatee ahora con Soporte
Chat con el soporte

Identity Manager 8.2 - 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 methods API Server ImxClient command line program

Response codes

Responses that are sent from the REST API use the following codes. If queries fail, an explanatory error message is displayed.

Response codes

Description

200

Query successful.

204

Query successful. Response has no content.

401

Access not authorized. The session must be authorized first.

404

The given resource could not be found.

405

The HTTP method used is not allowed for this query.

500

A server error occurred. The error message is sent with the response. On the ground of security, a detailed error message is not included in the response. For more information, see the application log file on the server.

Related topics

General notes and information about entity methods

In this section, you will find advice and information for creating and implementing entity methods.

Limiting results

NOTE: Entity-based methods normally work with a limit to avoid unintentionally loading extremely large amounts of data.

The following query parameters help you to limit the amount of data that is returned by obtaining multiple data sets from sequential responses:

Query parameter Default value Description
PageSize 20

Specifies the maximum number of data sets that can be contained in the response.

If you only determine the total number and do not want to obtains single data sets, use the value -1.

StartIndex 0

Specifies as from which data sets the results are returned in the response.

This parameter is null-based (the first element is addressed with the value 0).

Example

The following query returns 50 employees and starts with the 101st employee:

https://<Host-Name>/ApiServer/portal/person?PageSize=50&StartIndex=100

Sort order

Use the Orderby query parameter to sort the results returned in an response. This parameter allows you to sort the column names of the underlying database table.

Examples

The following query returns employees sorted by first name in ascending order:

https://<Host-Name>/ApiServer/portal/person?OrderBy=FirstName

Employees sorted by first name in descending order:
https://<Host-Name>/ApiServer/portal/person?OrderBy=FirstName%20DESC

Filtering

Use the filter query parameter to filter the results returned in an response. A filter like this consists of a JSON formatted string that must contain the following:

  • ColumnName: Name of the column used to filter
  • CompareOp: The operator for comparing the contents of the selected column with the expected value

    The following comparison operators are permitted:

    • Equal: The results only include data sets with column data that matches the comparison value.

    • NotEqual: The results only include data sets with column data that does NOT match the comparison value.

    • LowerThan: The results only include data sets with column data less than the comparison value.

    • LowerOrEqual: The results only include data sets with column data less than or equal to the comparison value.

    • GreaterOrEqual: The results only include data sets with column data greater than or equal to the comparison value.

    • Like: Requires the use of a percent sign (%) as a placeholder. You can enter up to two percent signs in this value. The results only include data sets with column data that matches the comparison value pattern.

    • NotLike: Requires the use of a percent sign (%) as a placeholder. You can enter up to two percent signs in this value. The results only include data sets with column data that does NOT match the comparison value pattern.

    • BitsSet: The value is compared to the comparison value using the AND (&) logical operator. The result must not be equal to 0.

    • BitsNotSet: The value is compared to the comparison value using the AND (&) logical operator. The result must be equal to 0.

  • Value1: Comparison value for comparing the contents of the column

  • Value 2: If this second comparison value is passed down, the value of CompareOp is ignored and all the values that are greater or equal to Value1 and less or equal to Value2 are determined.

Example

The following query returns all employees with the last name "Smith":

https://<Host-Name>/ApiServer/portal/person/all?filter=[{ColumnName: 'LastName', CompareOp: 'Equal', Value1: 'Smith'}]

Grouping

NOTE: The API method must support grouping (by using the EnableGrouping parameter).

Use the group URL parameter to group the results returned in an response. Use the by query parameter to specify which attribute to use for grouping.

The result of the query contains a filter condition that you can pass to the URL parameter as filter.

Example

The following queries determine the number of employees grouped by primary location:

https://<Host-Name>/ApiServer/portal/person/all/group?by=UID_Locality

Response:

{
    {
        "Display": "(No value: Primary location)",
        "Filters": [
            {
                "ColumnName": "UID_Locality",
                "CompareOp": 0
            }
        ],
        "Count": 42
    },
    {
        "Display": "Berlin",
        "Filters": [
            {
                "ColumnName": "UID_Locality",
                "CompareOp": 0,
                "Value1": "c644f672-566b-4ab0-bac0-2ad07b6cf457"
            }
        ],
        "Count": 12
    }
}
Hierarchical data structure

Some data model tables are defined as hierarchical structures (Department for example). In principle, data is loaded from such tables from a specific hierarchy level.

Use the parentKey query parameter and the UID of the parent object to specify the hierarchy level.

Example

https://<host name>/ApiServer/portal/servicecategories?parentKey=QER-f33d9f6ec3e744a3ab69a474c10f6ff4

Use the noRecursive=true URL parameter to query the data as flat list.

Example

https://<Host-Name>/ApiServer/portal/servicecategories?noRecursive=true

Related topics

Avoiding deadlocks

API development includes a lot of asynchronous code with async/await constructs. To avoid deadlocks, use the ConfigureAwait(false) method for every await keyword.

NOTE: When you compile the API, it checks whether ConfigureAwait(false) is used.

For more information, see https://blog.stephencleary.com/2012/07/dont-block-on-async-code.html and https://devblogs.microsoft.com/dotnet/configureawait-faq/.

Examples and help – Software Development Kit

To make it easier for you to start developing your API with the API Designer, One Identity provides a Software Development Kit (SDK) with lots of commented code example.

The SDK can be found on the installation medium in the directory QBM\dvd\AddOn\ApiSamples.

Documentos relacionados

The document was helpful.

Seleccionar calificación

I easily found the information I needed.

Seleccionar calificación