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
