OData API
The Thinkwise Indicium application tier offers an open API that can be used to perform CRUD-operations and execute procedures on the applications that have been made with the Thinkwise Platform. Through Indicium, a user will only have access to those tables, views and procedures for which the user has been authorized in IAM.
Indicium implements version 4.0 of the OData standard. The OData standard is well documented and as such this manual will not explain all of its features in detail. The OData documentation can be found using the link http://www.odata.org/documentation/.
Base URL
To access the API of a specific application, the URL of the request must always start with:
<web_app_root_url>/iam/<appl>/
In this template, <web_app_root_url>
refers to the root URL of Indicium in IIS and <appl>
refers to the ID
or the alias of the application in question in IAM. Below, you will find two examples of valid base-URLs:
<https://server/indicium/iam/123/>
<https://server/indicium/iam/insights/>
All requests that start with this base-URL will be subjected to authentication. The type of authentication used depends on the configuration of the user in question in IAM. All authentication follows the HTTP Basic authentication scheme, meaning that Indicium should only be exposed to the Internet over HTTPS.
Indicium running on a 2018.2 and earlier IAM must use <web_app_root_url>/api/<appl>/
instead.
Software Factory
The Indicium API provides access to project versions in the Software Factory development environment, as long as the Software Factory itself is available through the Indicium IAM.
<web_app_root_url>/sf/<sf_appl>/
The segment <sf_appl> refers to the application ID or application alias which can be found in the Software Factory at the desired runtime configuration. The runtime configuration must be activated for the user in the Software Factory to obtain access via Indicium.
For example:
<https://server/indicium/sf/144/>
<https://server/indicium/sf/insights/>
Or, if you are using Universal GUI:
https://server/indicium/iam/sf/
On the off-chance that there are multiple Software Factory applications in IAM, the segment /sf/ can be substituted with the alias of another Software Factory application.
Standard operations
Indicium offers several standard operations that can be performed on every application.
Metadata
With the standard operation **metadata` behind the base URL of the application.
The metadata document contains an extensive description of all entities and operations available for that particular user in that particular application. You can use it to validate whether a user's permissions in IAM have been configured properly. It can also serve as a guideline for writing your own Indicium client.
Open API
With the standard operation /openapi, you can retrieve the API specification for an application in JSON format.
To do this, add /openapi
behind the base URL of the application.
The API specification can be used by third-party tools to generate code or documentation. Copy-paste the JSON content into the editor to provide a web-based UI with information about your API. Examples include:
- NSwagStudio for code generation.
- Swagger for documentation generation.
- Postman for API testing. Postman will use the schemas defined in the API specification to create a new collection and automatically generate request and response bodies.
Refresh model
Windows GUI Web GUI IndiciumThe standard operation Refresh model can be accessed from the ribbon tab Developer in the Windows or Web GUI. It is also available as the /refresh_model API endpoint in the Indicium application tier. To reload (refresh) the model, send a POST request to one of the following URLs:
<web_app_root_url>/sf/<appl>/refresh_model
<web_app_root_url>/iam/<appl>/refresh_model
OData Service Document
With the standard operation /application.svc, you can retrieve the OData Service Document.
This is a metadata document that contains all of the top-level feeds that are exposed for an application model.
To do this, add /application.svc
behind the base URL of the application, using the format <application_root>/application.svc
.
For example, https://my_server/indicium/iam/appl/application.svc
.
The OData Service Document can be used by clients to discover the feeds that a service offers. Some clients rely on this Service Document, such as OData Feed, which can be used in PowerBI queries.
Performing CRUD-operations, functions and procedures
Aside from the standard operations, the Indicium API offers the ability to perform CRUD-operations on entities and to
execute tasks, reports, functions and procedures on the database.
Note that every insert, update, task and report action is done by Indicium via a process
called resource staging.
For a more detailed explanation of this process and a description of the available endpoints and operations on each endpoint, see Resource Staging.
API action | HTTP Verb | Example request |
---|---|---|
Selecting an entity | GET | Request URL to retrieve all records from the project entity:<https://server/indicium/iam/appl/project> Request URL to retrieve a specific record from the project entity given that it only has one numerical primary key column: <https://server/indicium/iam/appl/project(123)> Request URL to retrieve a specific record from the sub_project entity which has a primary key of project_id and sub_project_id: <https://server/indicium/iam/appl/sub_project(project_id=123,sub_project_id=321)> Request URL to retrieve the first 100 records from the project entity where the project_id is greater than 100, ordered by the project ID in ascending order: https://server/indicium/iam/appl/project?$top=100&$select=project_id, description&$filter=project_id gt 100&$orderby=project_id asc |
Inserting an entity | POST | Request URL to insert a new record into the project entity:<https://server/indicium/iam/appl/project> Request body assuming that project_id is not an identity: {"project_id": 123, "description": "a new project", "deadline": "2017-01-01T12:00:00.000"} Only one record can be inserted per request. All query string parameters will be ignored. See also Resource Staging. |
Inserting a detail entity | POST | Request URL to insert a new subproject record in the context of the project entity: <https://server/indicium/iam/appl/project(1)/detail_ref_project_subproject> Request body: {"subproject_name": "Documentation"} Only one record can be inserted per request. All query string parameters will be ignored. The last part of the url is the name of the reference prefixed by detail_ . The context of the parent record is automatically filled in by Indicium. |
Updating an entity | PATCH | Request URL to update the description of an existing record of the project entity:<https://server/indicium/iam/appl/project(123)> Request body: {"description": "a changed project"} Records can only be updated by specifying their entire primary key between the parentheses. All query string parameters will be ignored. See also Resource Staging. |
Deleting an entity | DELETE | To delete an existing record of the project entity: <https://server/indicium/iam/appl/project(123)> Records can only be deleted by specifying their entire primary key between the parentheses. All query string parameters will be ignored. |
Executing a task | POST | Request URL to call the task my_task with parameters project_id and description: <https://server/indicium/iam/appl/my_task> Request body: {"project_id": 123, "description": "my project"} All query string parameters will be ignored. See also Resource Staging. |
Executing a task on a record | POST | Request URL to call the task generate_invoice with parameters in the context of a project. The table task parameters are automatically filled in by Indicium.<https://server/indicium/iam/appl/project(1)/task_generate_invoice> Request body: {"month": 1} |
Executing a task on an empty detail | POST | Request URL to call the task create_default_subprojects on the subproject subject with parameters. The task is executed within the context of a project. <https://server/indicium/iam/appl/project(1)/ empty_detail_ref_project_subproject/task_create_default_subprojects> Request body: {"create_default_activities": true} The context of the parent record is automatically filled in by Indicium. |
Exporting a report | POST | Request URL to call the report my_report with parameters project_id and description: <https://server/indicium/iam/appl/my_report> Request body: {"project_id": 123, "description": "my project"} All query string parameters will be ignored. See also Resource Staging. |
Calling a function | GET | Request URL to call the function my_function with parameters project_id and description: https://server/indicium/iam/appl/my_function(project_id=123,description='my project' )All query string parameters will be ignored. |
Calling a procedure | POST | Request URL to call the procedure my_procedure with parameters project_id and description: <https://server/indicium/iam/appl/my_procedure> Request body: {"project_id": 123, "description": "my project"} All query string parameters will be ignored. |
It is important to apply URL encoding (also known as Percent-encoding) to all value literals in the request URL. Value
literals can only occur between the parentheses ( )
after the name of an entity and in the value of the $filter
query string parameter.
Subroutines
For security reasons, subroutines are not exposed by the Indicium OData API by default.
To expose a subroutine using Indicium, enable the API
option of the subroutine in the Software Factory.
The service name of a subroutine and its parameters can be changed using the Alias
settings.
Supported OData operations
Indicium supports the following OData operations and query string options in the URL:
- $metadata
- $top
- $skip
- $select
- $filter
- $search
- $orderby
- $expand
- $apply (with groupby or standard computations)
- $query
- $seek
- Use OData query options like search or $orderby to filter and/or order a set of records.
- Use $seek to search within this filtered and sorted set.
Top
To get the number of records in a table without getting actual data, use a $top=0&$count=true
query.
Template: http://server/indicium/iam/123/table?$top=0&$count=true
Example: https://xxx.thinkwise.app/indicium/iam/265/uur?$top=0&$count=true
Response: {"@odata.context":"https://tcp.thinkwise.app/iam/265/$metadata#uur","@odata.count":598325,"value":[]}
Filter
Indicium supports filtering on and ordering by the display value of a lookup. This can be achieved by specifying
reference_id/display_column_id
in the request URL, rather than simply the ID of the column. For example:
<http://server/indicium/iam/123/table?$filter=contains(reference_id/display_column_id,'value')>
In addition to the standard OData operations, Indicium also supports a custom $prefilter operation which can be used to add prefilters to requests in order to select records from entities. For example:
<http://server/indicium/iam/123/table?$prefilter=prefilter_1,prefilter_2>
Search
The $search query option can be used to retrieve all records that match a free-text search expression. For example:
<http://server/indicium/iam/123/project?$search="my project">
You can only search in columns included in the combined filter.
Seek
When the custom $seek query option is used, Indicium will return the row index of the records that match the given filter condition. For example:
<http://server/indicium/iam/123/project?$seek=contains(name,'my project')>
The response of a $seek request will look like this:
{
"value":
[
{
"row_index@odata.type": "#Int64",
"row_index": 1,
"project_id":1,
"name":"my project"
},
{
"row_index@odata.type": "#Int64",
"row_index": 2,
"project_id":10,
"name":"this is also my project"
}
]
}
Expand
The $expand operation allows you to select any properties from the entity on the other side of the navigation property. The navigation properties for lookups will always lead to the entity that contains the display property of the lookup, which is not necessarily the same entity as the source_tab of the corresponding lookup reference.
Examples:
<http://server/indicium/api/123/sub_project?$expand=transl_project_id>
To select all columns from sub_project and project.<http://server/indicium/api/123/sub_project?$select=project_id&$expand=transl_project_id($select=description)>
To select project_id from sub_project and description from project.
When using select,