You can use the imx/sessions/<API project name> API method to query the status of the session. The response contains the following information:
You can define the following types of API methods.
Entity methods
Entity methods work with small parts of the object model in order to read data from the database or write data to the database. When you create an entity method, you only need to enter the table and column name and, if required, a filter condition (WHERE clause). Internal processing is handled by the API Server. The data schema for the input and output also has a specific format.
For examples for the definition of entity methods, see the SDK under Sdk01_Basics\01-BasicQueryMethod.cs.
User-defined methods
User-defined methods are methods for which you fully define the processing, input, and output data in code. This type therefore offers the greatest flexibility.
For examples for the user-defined methods, see the SDK under Sdk01_Basics\03-CustomMethod.cs.
SQL methods
SQL methods are methods that provide data from a predefined SQL query through the API. Create the parameters of a query as SQL parameters.
For examples for the definition of SQL methods, see the SDK under Sdk01_Basics\02-BasicSqlMethod.cs.
Detailed information about this topic
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:
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 in descending order by first name:
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 "User1":
https://<Host-Name>/ApiServer/portal/person/all?filter=[{ColumnName: 'LastName', CompareOp: 'Equal', Value1: 'User1'}]
Grouping
You can use the group path parameter to group the results returned in a response. You can use the by query parameter to specify which attribute to use for grouping. Furthermore, you can use the withcount query parameter to specify (values: true or false) whether to calculate the number of objects for each group. This may increase the runtime.
NOTE: The API method must support grouping (by using the EnableGrouping parameter).
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 identities grouped by primary location:
https://<host name>/ApiServer/portal/person/all/group?by=UID_Locality&withcount=true
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). Data from such tables is loaded from a specific hierarchy level.
You can use the parentKey query parameter of the parent object to specify the hierarchy level.
Example
The following query determines the service categories directly below the Access Lifecycle service category:
https://<host name>/ApiServer/portal/servicecategories?parentKey=QER-f33d9f6ec3e744a3ab69a474c10f6ff4
The following query determines the service categories that do not have a parent service category:
https://<Host-Name>/ApiServer/portal/servicecategories?parentKey=
The following query determines all service categories regardless of their hierarchy:
https://<Host-Name>/ApiServer/portal/servicecategories
You can use the noRecursive path parameter to specify whether the data is queried as a flat list (values: true or false).
Example
https://<Host-Name>/ApiServer/portal/servicecategories?noRecursive=true
Additional query parameters
You can use the withProperties query parameter to specify whether additional information from specific tables columns are returned in the response.
NOTE: To enable table columns for these queries, set the Show in wizards option in the column properties of the relevant columns in the Designer.
TIP: You can delimit the names of multiple columns with commas.
Example
The following query determines the number of all identities and also returns their preferred name and title:
https://<host name>/ApiServer/portal/person/all?withProperties=PreferredName,Title
Response:
{ |
"TotalCount": 105950, |
"TableName": "Person", |
"Entities": [ |
{ |
"Display": "100, User (USER1)", |
"LongDisplay": "100, User (USER1)", |
"Keys": [ |
"bbf3f8e6-b719-4ec7-be35-cbd6383ef370" |
], |
"Columns": { |
"DefaultEmailAddress": { |
"Value": "USER1@qs.ber", |
"IsReadOnly": true |
}, |
"IdentityType": { |
"Value": "Primary", |
"IsReadOnly": true, |
"DisplayValue": "Primary identity" |
}, |
"PreferredName": { |
"Value": "Johnny", |
"IsReadOnly": true |
}, |
"Title": { |
"Value": "Dr.", |
"IsReadOnly": true |
}, |
"XObjectKey": { |
"Value": "<Key><T>Person</T><P>bbf3f8e6-b719-4ec7-be35-cbd6383ef370</P></Key>", |
"IsReadOnly": true |
} |
} |
} |
HTTP requests can apply the following HTTP methods:
-
GET: This method requests data from the application server.
-
PUT: This method changes data on the application server.
-
POST: This method creates data on the application server.
-
DELETE: This method deletes data on the application server.