Access to Endpoint functions via API
Access to Endpoint functions via API¶
Introduction¶
CCH Tagetik also allows endpoints to be managed via APIs (RESTful APIs).
Certain conditions are required to use this consultation mode.
Access conditions¶
To be able to use these specific APIs, the user must be authenticated (Basic Auth, OAuth2).
APIs must also be enabled in the Repository. For reverse proxies, further settings are necessary. They can be used with both http and https protocols.
For more details on authentication and enabling, see REST API Overview.
API to read default Endpoints¶
Method¶
GET
URL¶
http://server:port/tagetikcpm/api/admintools/endpoint/v1/default
API to read all Endpoints¶
Method¶
GET
URL¶
http://server:port/tagetikcpm/api/admintools/import/v1/elements
API to read all Endpoints filtered by code¶
Method¶
GET
URL¶
http://server:port/tagetikcpm/api/admintools/import/v1/elements?filter=code_filter
API to read a single Endpoint¶
Method¶
GET
URL¶
http://server:port/tagetikcpm/api/admintools/import/v1/elements/endpoint_code
API to create a new Endpoint¶
Method¶
POST
URL¶
http://server:port/tagetikcpm/api/admintools/import/v1/elements
Property¶
In the body of the request it is possible to include the following properties in JSON format:
| Property | Description | Options |
|---|---|---|
| code | Mandatory. | - |
| description | Mandatory. | - |
| endpointType | Mandatory. | It can take the following values: - U: URL - A: Tagetik Data Loader - P: Application - O: OData V4 - 2: OData V2 - R: REST API - S: SharePoint - B: Google Big Query - F: Snowflake |
endpointType properties¶
Moreover, depending on the endpoint type it is possible to add the following properties:
| URL: properties | Description | Options |
|---|---|---|
| url | Mandatory. | - |
| defaultEndpoint | - | true/false (default = false) |
| authenticationType | - | It can take the following values: - N: None (default) - B: Basic |
| basicUsername | Mandatory if authenticationType = B. | - |
| basicPassword | Defined if authenticationType = B. | - |
| pgpEnabled | - | true/false (default = false) |
| pgpPublicKey | Mandatory if pgpEnabled = true | - |
| pgpPrivateKey | Mandatory if pgpEnabled = true | - |
| pgpPassphrase | mandatory if pgpEnabled = true | - |
| Agent: properties | Description | Options |
|---|---|---|
| tdlAgentId | Mandatory. | - |
| tdlSourceType | Mandatory. | It can take the following values: - P: Path - D: Datasource |
| tdlPath | Mandatory if tdlSourceType = P | - |
| tdlDatasource | Mandatory if tdlSourceType = D | - |
| pgpEnabled | - | true/false (default = false) |
| pgpPublicKey | Mandatory if pgpEnabled = true | - |
| pgpPrivateKey | Mandatory if pgpEnabled = true | - |
| pgpPassphrase | Mandatory if pgpEnabled = true | - |
| Application: properties | Description | Options |
|---|---|---|
| url | Mandatory. | - |
| applicationDatasource | Mandatory. | - |
| Odata (V4, V2): properties | Description | Options |
|---|---|---|
| url | Mandatory. | - |
| odataPaginationSize | Mandatory. | >= 0 (default = 0) |
| authenticationType | Mandatory. | It can take the following values: - N: None (default) - B: Basic - O: OAuth2.0 |
| basicUsername | Mandatory if authenticationType = B | - |
| basicPassword | Defined if authenticationType = B | - |
| oauth2GrantType | Defined if authenticationType = O | It can take the following values: - CLIENT (default) - PASSWORD |
| oauth2TokenEndpoint | Mandatory if authenticationType = O | - |
| oauth2ClientId | Mandatory if authenticationType = O | - |
| oauth2ClientSecret | Mandatory if authenticationType = O | - |
| oauth2Username | Mandatory if authenticationType = O e oauth2GrantType = PASSWORD | - |
| oauth2Password | Mandatory if authenticationType = O e oauth2GrantType = PASSWORD | - |
| oauth2Scopes | Defined if authenticationType = O | - |
| oauth2Resources | Defined if authenticationType = O | - |
| oauth2ClientAuthentication | Defined if authenticationType = O | It can take the following values: - HEADER(default) - BODY - JWT |
| oauth2Kid | The Header parameter 'kid' (key ID) is a hint as to which key was used to protect JWS. Defined if authenticationType = O and oauth2GrantType = CLIENT and oauth2ClientAuthentication = JWT | - |
| oauth2Lifetime | The duration is the time in seconds added to the iat (issue at time) to create the JWT expiration time at or after which the JWT MUST NOT be accepted for data processing). Defined if authenticationType = O and oauth2GrantType = CLIENT and oauth2ClientAuthentication = JWT | >= 1 and <= 3600 (default = 300) |
| jwtCertificateFile | Generated private key code in PEM format. Mandatory if authenticationType = O and oauth2GrantType = CLIENT and oauth2ClientAuthentication = JWT | - |
| oauth2UseProxy | - | true/false (default = false) |
| oauth2UseCertificates | - | true/false (default = false) |
| proxyServer | - | - |
| proxyServerPort | - | - |
| proxyUsername | - | - |
| proxyPassword | - | - |
| customHeaders | - | - |
| REST API: properties | Description | Options |
|---|---|---|
| url | Mandatory. | - |
| restResponseType | Mandatory. | It can take the following values: - JSON (default) - CSV |
| restPath | Defined if restResponseType = JSON | - |
| restJsonArrayLevel | - | >= 0 (default 0) |
| restCsvHeader | Defined if restResponseType = CSV | true/false (default = false) |
| restCsvColumnSeparator | Mandatory if restResponseType = CSV | It can take the following values: - "," (default) - ";" - " |
| restCsvValueDelimiterMode | Mandatory if restResponseType = CSV | It can take the following values: - NONE (default) - MINIMAL - NON_NUMERIC - ALL |
| restCsvValueDelimiter | Mandatory if restResponseType = CSV | It can take the following values: - N (default) - " - ' |
| restCsvRowSeparator | Mandatory if restResponseType = CSV | It can take the following values: - CRLF (default) - CR - LF |
| restPaginationUsage | Mandatory. | It can take the following values: - N: None (default) - H: Header - Q: Query param |
| restPaginationPropertyName | Mandatory only if restPaginationUsage = H or Q | - |
| restPaginationSize | Mandatory only if restPaginationUsage = H o Q | Must be > 0 |
| restNextPageResponsePosition | Mandatory. | It can take the following values: - N: None (default) - H: Header - B: Body attribute (only if restResponseType = JSON) |
| restNextPageResponsePropertyName | Mandatory only if restPaginationUsage = H or B | - |
| restNextPageRequestPosition | Mandatory. | It can take the following values: - N: None (default) - H: Header - Q: Query param - U: Complete URL |
| restNextPageRequestPropertyName | Mandatory only if restPaginationUsage = H o Q | - |
| authenticationType | Mandatory. | It can take the following values: - N: None (default) - B: Basic - O: OAuth2.0 |
| basicUsername | Mandatory if authenticationType = B. | - |
| basicPassword | Defined if authenticationType = B | - |
| oauth2GrantType | Defined if authenticationType = O | It can take the following values: - CLIENT (default) - PASSWORD |
| oauth2TokenEndpoint | Mandatory if authenticationType = O | - |
| oauth2ClientId | Mandatory if authenticationType = O | - |
| oauth2ClientSecret | Mandatory if authenticationType = O | - |
| oauth2Username | Mandatory if authenticationType = O e oauth2GrantType = PASSWORD | - |
| oauth2Password | Mandatory if authenticationType = O e oauth2GrantType = PASSWORD | - |
| oauth2Scopes | Defined if authenticationType = O | - |
| oauth2Resources | Defined if authenticationType = O | - |
| oauth2ClientAuthentication | Defined if authenticationType = O | It can take the following values: - HEADER (default) - BODY - JWT |
| oauth2Kid | The Header parameter 'kid' (key ID) is a hint as to which key was used to protect JWS. Defined if authenticationType = O and oauth2GrantType = CLIENT and oauth2ClientAuthentication = JWT | - |
| oauth2Lifetime | The duration is the time in seconds added to the iat (issue at time) to create the JWT expiration time at or after which the JWT MUST NOT be accepted for data processing). Defined if authenticationType = O and oauth2GrantType = CLIENT and oauth2ClientAuthentication = JWT | >= 1 and <= 3600 (default = 300) |
| jwtCertificateFile | Generated private key code in PEM format. Mandatory if authenticationType = O and oauth2GrantType = CLIENT and oauth2ClientAuthentication = JWT | - |
| oauth2UseProxy | - | true/false (default = false) |
| oauth2UseCertificates | - | true/false (default = false) |
| proxyServer | - | - |
| proxyServerPort | - | - |
| proxyUsername | - | - |
| proxyPassword | - | - |
| customHeaders | - | - |
The certificates cannot be configured via API
| Sharepoint: properties | Description | Options |
| sharepointTenantId | Mandatory | - |
| sharepointClientId | Mandatory | - |
| sharepointSiteName | Mandatory | - |
| sharepointScope | - | - |
| sharepointAuthenticationType | Mandatory | It can take the following values: - S: Secret Note: the field can take the read-only value C (Certificate) |
| sharepointSecretValue | Mandatory | - |
| MS Fabric: properties | Description | Options |
| fabricSqlEndpoint | Mandatory | SQL Warehouse Endpoint |
| fabricWarehouse | Mandatory | Warehouse Name |
| fabricTenantId | Mandatory | Tenant Id |
| fabricClientId | Mandatory | Apllication Azure client id |
| fabricSecret | Mandatory | Secret generated for Application Azure. |
Certificate authentication is not managed via API.
Creation, replacement, update, and deletion operations for Google BigQuery and Snowflake endpoints are not allowed when using the REST API service. Executing these operations will return a ‘501 – Not Implemented’ response.
API to replace an Endpoint¶
Method¶
PUT
URL¶
http://server:port/tagetikcpm/api/admintools/import/v1/elements/endpoint_code
Property¶
In the body of the request, in JSON format, it is possible to include the same properties as in the creation according to the type of endpoint, with the exception of 'code', which is already specified in the url.
For an endpoint with oauth2ClientAuthentication = JWT, this operation will have no effect (400 - Bad request: The following endpoint cannot be replaced:
API to update an Endpoint¶
Method¶
PATCH
URL¶
http://server:port/tagetikcpm/api/admintools/import/v1/elements/endpoint_code
Property¶
In the body of the request, in JSON format, it is possible to include, as properties to be updated, the same as the creation according to the type of endpoint, with the exception of the following fields which cannot be changed:
- code
- endpointType
- tdlAgentId
- tdlSourceType
- sharepointAuthenticationType
Other non-editable fields belong to the case of an endpoint modification with oauth2ClientAuthentication = JWT:
- authenticationType
- oauth2GrantType
- oauth2ClientAuthentication
- jwtCertificateFile
API to delete an Endpoint¶
Method¶
DELETE
URL¶
http://server:port/tagetikcpm/api/admintools/import/v1/elements/endpoint_code