API Documentation

REST - InstanceControl

REST-Interface

Signup

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

Creates and inits another instance. This also creates a credential and the corresponding person (account/contact) as instanceadmin with all initial functional roles assigned (including admin). At least this updates the licence for the newly created instance.
You can set a password optionally. Therfore set Signup.password AND Signup.updatePassword = true. If updatePassword is false a Credential without password will be created! Only in this case an E-Mail notification with link will be sent.
URL
POST <application-url>/api/instancecontrol/signup

Query parameter

  • languageKey
    possible: de, en, …
    default: en
    language-key for email-notification

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Signup

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 201 CREATED
  • 500 INTERNAL_SERVER_ERROR

Permission
systemAccountRequired

Sample
POST http://localhost:8080/mtr-backend/api/instancecontrol/signup

Create instance

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

URL
POST <application-url>/api/instancecontrol/instance

Consumes

application/json
application/xml

com.matterial.mtr.api.object.WildflyDataSource

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 201 CREATED
  • 500 INTERNAL_SERVER_ERROR

Permission
systemAccountRequired

Sample
POST http://localhost:8080/mtr-backend/api/instancecontrol/instance

Change instance

Attention:
Won’t work on multiserve-installation.
Use Logon.preChangeinstance-API!

URL
PUT <application-url>/api/instancecontrol/instance/<dataSourceName>

Path parameter

  • dataSourceName
    datasource / instance

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 202 ACCEPTED
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/instance/MtrInst2DS

Change instance by id

Attention:
Won’t work on multiserve-installation.
Use Logon.preChangeinstance-API!

URL
PUT <application-url>/api/instancecontrol/instance/byid/<dataSourceId>

Path parameter

  • dataSourceId
    datasource- / instance-id

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 202 ACCEPTED
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/instance/byid/4

Get invitees with no account

Get all invitees, that do not exist in instance yet.
URL
GET <application-url>/api/instancecontrol/credential/invitee

Produces

application/json
application/xml

List<com.matterial.mtr.api.object.Credential>

  • 200 OK
  • 400 BAD_REQUEST
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, instanceOwnerRequired

Sample
GET http://localhost:8080/mtr-backend/api/instancecontrol/credential/invitee

Reinvite credential

This resends the invitation mail to the invitee and renews its LoginToken.
URL
PUT <application-url>/api/instancecontrol/credential/invitee/<credentialId>

Path parameter

  • credentialId

Query parameter

  • languageKey
    possible: de, en, …
    default: en
    language-key for email-notification

Produces

  • 202 ACCEPTED
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/credential/invitee/5

Remove invitee

Remove the credential from current instance. Additionally this removes the whole credential if no more related instances are left.
URL
DELETE <application-url>/api/instancecontrol/credential/invitee/<credentialId>

Path parameter

  • credentialId

Produces

text/plain

[Integer] count of removed invitees

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired

Sample
DELETE http://localhost:8080/mtr-backend/api/instancecontrol/credential/invitee/5

Store credential with data-sources

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

This is only available for system-account. This sets the password and is the only possibility to store credentials for several data-sources.
URL
PUT <application-url>/api/instancecontrol/credential/withdatasources

Consumes

application/json
application/xml

com.matterial.mtr.api.object.Credential

Produces

text/plain

Long - credential-id

  • 202 ACCEPTED
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, systemAccount

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/credential/withdatasources

Store credential

This is only available for instance-admins. Instance-Admins can only create credentials within the current instance (datasource). Credential.password and Credential.dataSources will be ignored. The current instance will be added to the existing. Set Credential.limited=true to create (“invite”) a user with limited permissions. An E-Mail-notification-link will be created to login without password.
URL
PUT <application-url>/api/instancecontrol/credential

Query parameter

  • languageKey
    possible: de, en, …
    default: en
    language-key for email-notification

Consumes

application/json
application/xml

com.matterial.mtr.api.object.CredentialWithInvitationText

Produces

text/plain

Long - credential-id

  • 202 ACCEPTED
  • 400 BAD REQUEST
    • system
    • myself
    • already assigned credential
  • 401 UNAUTHORIZED
  • 402 PAYMENT_REQUIRED
  • 403 FORBIDDEN
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, instanceAdmin

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/credential

Store credentials

This is only available for instance-admins. Instance-Admins can only create credentials within the current instance (datasource). Credential.password and Credential.dataSources will be ignored. The current instance will be added to the existing. Set Credential.limited=true to create (“invite”) a user with limited permissions. An E-Mail-notification-link will be created to login without password.
URL
PUT <application-url>/api/instancecontrol/credential/list

Query parameter

  • languageKey
    possible: de, en, …
    default: en
    language-key for email-notification

Consumes

application/json
application/xml

List<com.matterial.mtr.api.object.CredentialWithInvitationText>

Produces

application/json
application/xml

List<Long> - credential-ids

  • 202 ACCEPTED
  • 400 BAD REQUEST
    • system
    • myself
    • already assigned credential
  • 401 UNAUTHORIZED
  • 402 PAYMENT_REQUIRED
  • 403 FORBIDDEN
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, instanceAdmin

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/credential/list

Update favourite data-source

URL
PUT <application-url>/api/instancecontrol/credential/favdatasource

Consumes

application/json
application/xml

com.matterial.mtr.api.object.DataSource

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/credential/favdatasource

Get instance by id

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

URL
GET <application-url>/api/instancecontrol/instance/<dataSourceId>

Path parameter

  • dataSourceId
    datasource- / instance-id

Produces

application/json
application/xml

com.matterial.mtr.api.object.DataSource

  • 200 OK
  • 400 BAD_REQUEST
  • 404 NOT_FOUND
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, systemAccountRequired

Sample
GET http://localhost:8080/mtr-backend/api/instancecontrol/instance/1

Get instances

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

URL
GET <application-url>/api/instancecontrol/instance

Query parameter

  • dataSourceId
    datasource- / instance-id
  • active
    possible: true, false
    filter by active
  • accountLogin
    filter by credential
  • dataSourceName
    filter by name
  • dataSourceReference
    filter by reference
  • count
    possible: true, false
    default: false
    get count
  • orderByStr
    id
    name
    displayName
    reference
    active
    default: active
    order by
  • orderByDir
    possible: asc, desc
    default: asc
    order by direction
  • offset
    default: 0
  • limit
    default: 0

Produces

application/json
application/xml

com.matterial.mtr.api.object.ListResult<DataSource>

  • 200 OK
  • 400 BAD_REQUEST
  • 404 NOT_FOUND
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, systemAccountRequired

Sample
GET http://localhost:8080/mtr-backend/api/instancecontrol/instance?count=true

Update displayname of current datasource.

URL
PUT <application-url>/api/instancecontrol/instance/displayname/<displayName>

Path parameter

  • displayName

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
instanceOwnerRequired

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/instance/displayname/MyCompany

Activate instance (unlimited)

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

Activates an instance (datasource) for unlimited days.
URL
PUT <application-url>/api/instancecontrol/instance/<dataSourceName>/activate/unlimited

Path parameter

  • dataSourceName
    datasource-name

Produces

text/plain

[Integer] updated

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, systemAccountRequired

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/instance/MtrDS/activate/unlimited

Activate instance

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

Activates an instance (datasource) for the next specified days.
URL
PUT <application-url>/api/instancecontrol/instance/<dataSourceName>/activate/days/<days>

Path parameter

  • dataSourceName
    datasource-name
  • days
    days

Produces

text/plain

[Integer] updated

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, systemAccountRequired

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/instance/MtrDS/activate/days/30

Deactivate instance

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

Deactivates an active instance (datasource).
URL
PUT <application-url>/api/instancecontrol/instance/<dataSourceName>/deactivate

Path parameter

  • dataSourceName
    datasource-name

Produces

text/plain

[Integer] updated

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, systemAccountRequired

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/instance/MtrDS/deactivate

Remove instance

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

Removes inactive instance (datasource). Instance / DataSource has to be deactivated before removing it.
URL
DELETE <application-url>/api/instancecontrol/instance/<dataSourceName>

Path parameter

  • dataSourceName
    datasource-name

Produces

text/plain

[Boolean] success

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, systemAccountRequired

Sample
DELETE http://localhost:8080/mtr-backend/api/instancecontrol/instance/MtrDS

2FA - QR-Code

Get Two Factor Auth QR-Code.
URL
GET <application-url>/api/instancecontrol/twofactorauth/qrcode

Produces

  • 200 OK
  • 204 NO_CONTENT
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
GET http://localhost:8080/mtr-backend/api/instancecontrol/twofactorauth/qrcode

2FA - Activate

Activate Two Factor Auth for current user.
URL
POST <application-url>/api/instancecontrol/twofactorauth

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 201 CREATED
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
POST http://localhost:8080/mtr-backend/api/instancecontrol/twofactorauth

2FA - Authorize

Authorize the given Two Factor Auth verification code.
URL
PUT <application-url>/api/instancecontrol/twofactorauth

Consumes

text/plain

Integer - verification code

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 403 FORBIDDEN
  • 401 UNAUTHORIZED
  • 500 INTERNAL_SERVER_ERROR

Permission
Login, twoFactorAuthNotRequired

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/twofactorauth

2FA - Deactivate

Deactivate Two Factor Auth for current user.
URL
DELETE <application-url>/api/instancecontrol/twofactorauth

Produces

application/json
application/xml

com.matterial.mtr.api.object.LoginData

  • 200 OK
  • 500 INTERNAL_SERVER_ERROR

Permission
Login

Sample
DELETE http://localhost:8080/mtr-backend/api/instancecontrol/twofactorauth

Remove Index

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

This removes the complete index from filesystem of the current instance!
URL
DELETE <application-url>/api/instancecontrol/search/index

Produces

text/plain

boolean - true on success

  • 202 ACCEPTED
  • 500 INTERNAL_SERVER_ERROR

Permission
systemAccountRequired

Sample
DELETE http://localhost:8080/mtr-backend/api/instancecontrol/search/index

Reindex all instances

Attention:
This API requires the systemAccount which is only available in on-premises installations (private cloud).

This removes the complete index from filesystem and reindexes all persons and documents for each instance.
URL
PUT <application-url>/api/instancecontrol/search/reindexall

  • 202 ACCEPTED
  • 500 INTERNAL_SERVER_ERROR

Permission
systemAccountRequired

Sample
PUT http://localhost:8080/mtr-backend/api/instancecontrol/search/reindexall

Contact sales