Skip to main content

REST API

Txture provides a REST API that can be used to...

  • get the state of the running Txture server as well as license information
  • get the configured information model (i.e. all classes, aspects, properties and associations defined in the modelDefinition.json
  • get information about all managed assets and associations
  • apply changes to the asset repository (i.e. adding, removing and modifying assets and associations)
  • executing queries on the Txture server
  • get information on managed external applications (i.e. access tokens for accessing the REST API)

Accessing and Browsing the API​

The Txture REST API can be accessed by authenticated users or external applications from your local installation and for a specific major version of Txture starting with major version 4. The URL for accessing the REST API for version 4 is therefore

http(s)://{txture.url}/api/v4

Info:

Please note:

In general Txture maintains versioned REST APIs for the current and the previous major release in order to allow for backwards compatibility. The URL schema to access the REST API for different versions is

http(s)://{txture.url}/api/v{major-version-identifier}

The documentation of the REST API and all its available versions can be accessed from your local installation at

http(s)://{txture.url}/api/docs

The following documentation page is available to authenticated users (i.e. users that are currently logged via the main application) and allows to browse the different REST API operations and to execute them manually. 

Warning:

It is important to note that all calls to the REST API via this documentation is actually executed on your local Txture server. E.g. deleting an asset will actually delete it from the asset repository. Still the REST calls are protected by authentication and the usual access control settings that apply to users and user roles. 

Managing External Applications ​

In order to access the REST API from within third party applications (in case they offer such a mechanism) or custom developed applications, API access tokens can be generated for them and used to authenticate calls via REST.

External applications, like regular users, can have roles and access control settings assigned. Administrators can manage external applications in a dedicated section in the admin area. For each managed external application an access token is generated and can be copied and used to authenticate REST API calls. Access tokens have a validity date set until they can successfully authenticate REST calls. Further, access tokens can be manually revoked, also restricting the access to the API.

Authentication Methods​

There are three possible ways of providing the access tokens to authenticate REST calls of external applications:

  • HTTP authorization header
  • URL request parameter
  • Cookie

HTTP Authorization Header​

To get REST API calls authenticated the HTTP authorization header can be used with the Bearer schema, which looks like the following: 

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

This header needs to be set on every single REST call.

Example

$ curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." http(s)://{txture.url}/api/v4/status

URL Request Parameter​

To get REST API calls authenticated the access_token URL request parameter can be added to the request.

Example

$ curl http(s)://{txture.url}/api/v4/status?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Cookies​

Cookies are primarily used by the Txture user application. In order to authenticate REST API calls via cookies, a cookie with the access_token key must be present.