Beschreibung der API#

Warnung

Aufgrund mangelnder Nutzung im Gegensatz zum erhöhten Pflegebedarf und Inkompatibilitäten mit der zukünftigen Entwicklung wurde die aktuelle API abgekündigt und sollte nicht weiter verwendet werden. Ein Großteil der Funktionen kann bereits vom IDM (https://idm.demo-iserv.de/iserv/idm/api/v1/docs?ui=redocs) übernommen werden.

IServ API

Base URL: /iserv/api, Version: 1.6.0

Default request content-types: application/json
Default response content-types: application/json
Schemes: https

Summary

Tag: IServ Core User

Operation Description
GET /IServ/Core/Entity/User

Returns all users

POST /IServ/Core/Entity/User

Creates a new user

GET /IServ/Core/Entity/User/{id}

Finds user by ID

PUT /IServ/Core/Entity/User/{id}

Updates user

DELETE /IServ/Core/Entity/User/{id}

Deletes a user

POST /IServ/Core/Entity/User/{id}/link/groups

Adds one or more group to the user

DELETE /IServ/Core/Entity/User/{id}/link/groups

Removes one or more group from the user

POST /IServ/Core/Entity/User/{id}/link/roles

Adds one or more role to the user

DELETE /IServ/Core/Entity/User/{id}/link/roles

Removes one or more role from the user

POST /IServ/Core/Entity/User/{id}/link/privileges

Adds one or more privilege to the user

DELETE /IServ/Core/Entity/User/{id}/link/privileges

Removes one or more privilege from the user

POST /IServ/Core/User/{id}/restore

Restores a deleted user

POST /IServ/Core/User/{id}/password

Sets the password of the user

POST /IServ/Core/User/{id}/password/reset

Resets the password of the user

POST /IServ/Core/User/{id}/adminpassword

Sets the administrator password of the user

POST /IServ/Core/User/{id}/adminpassword/reset

Resets the administrator password of the user

POST /IServ/Core/User/{id}/adminpassword/revoke

Removes the administrator password from the user

Tag: IServ Core Group

Operation Description
GET /IServ/Core/Entity/Group

Returns all groups

POST /IServ/Core/Entity/Group

Creates a new group

GET /IServ/Core/Entity/Group/{id}

Finds group by ID

PUT /IServ/Core/Entity/Group/{id}

Updates group

DELETE /IServ/Core/Entity/Group/{id}

Deletes a group

POST /IServ/Core/Entity/Group/{id}/link/users

Adds one or more user to the group

DELETE /IServ/Core/Entity/Group/{id}/link/users

Removes one or more user from the group

POST /IServ/Core/Entity/Group/{id}/link/assignedPrivileges

Adds one or more privilege to the group

DELETE /IServ/Core/Entity/Group/{id}/link/assignedPrivileges

Removes one or more privilege from the group

POST /IServ/Core/Entity/Group/{id}/link/assignedFlags

Adds one or more groupflag to the group

DELETE /IServ/Core/Entity/Group/{id}/link/assignedFlags

Removes one or more groupflag from the group

Tag: IServ Core Role

Operation Description
GET /IServ/Core/Entity/Role

Returns all roles

POST /IServ/Core/Entity/Role

Creates a new role

GET /IServ/Core/Entity/Role/{id}

Finds role by ID

DELETE /IServ/Core/Entity/Role/{id}

Deletes a role

POST /IServ/Core/Entity/Role/{id}/link/privileges

Adds one or more privilege to the role

DELETE /IServ/Core/Entity/Role/{id}/link/privileges

Removes one or more privilege from the role

Tag: IServ Core Privilege

Operation Description
GET /IServ/Core/Entity/Privilege

Returns all privileges

GET /IServ/Core/Entity/Privilege/{id}

Finds privilege by ID

POST /IServ/Core/Entity/Privilege/{id}/link/roles

Adds one or more role to the privilege

DELETE /IServ/Core/Entity/Privilege/{id}/link/roles

Removes one or more role from the privilege

POST /IServ/Core/Entity/Privilege/{id}/link/groups

Adds one or more group to the privilege

DELETE /IServ/Core/Entity/Privilege/{id}/link/groups

Removes one or more group from the privilege

Tag: IServ Sso

Operation Description
POST /IServ/Sso/authenticate

Paths

Returns all groups

GET /IServ/Core/Entity/Group

Tags: IServ Core Group
extended

Include list of IDs of related entities (if available)

query object

application/json

200 OK

A list of groups

object
account: string

Account

name: string

Name

owner: string

Owner

createdBy: string

Created by

created: date (date)

Created on

_id: string

The internal ID

400 Bad Request

Invalid request

Creates a new group

POST /IServ/Core/Entity/Group

Tags: IServ Core Group

Uses default content-types: application/json

Group object to create

name: string

Name

application/json

201 Created

Group creation successful

400 Bad Request

Invalid request

Deletes a group

DELETE /IServ/Core/Entity/Group/{id}

Tags: IServ Core Group
id

ID of group

path string

application/json

204 No Content

Operation successful

400 Bad Request

Invalid request

403 Forbidden

The group may not be deleted

404 Not Found

Not found

Finds group by ID

GET /IServ/Core/Entity/Group/{id}

Tags: IServ Core Group

Returns a single group

id

ID of group

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Updates group

PUT /IServ/Core/Entity/Group/{id}

Tags: IServ Core Group

Returns the updated group

Uses default content-types: application/json

Values to update group with - all optional.

name: string

Name

account: string

Account

id

ID of group

path string

application/json

200 OK

Operation successful

name: string

Name

account: string

Account

400 Bad Request

Invalid request

403 Forbidden

The group may not be updated

404 Not Found

Not found

Adds one or more groupflag to the group

POST /IServ/Core/Entity/Group/{id}/link/assignedFlags

Tags: IServ Core Group

Returns the updated group

Uses default content-types: application/json

Array of groupflag IDs

string
id

ID of group

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Adds one or more privilege to the group

POST /IServ/Core/Entity/Group/{id}/link/assignedPrivileges

Tags: IServ Core Group

Returns the updated group

Uses default content-types: application/json

Array of privilege IDs

string
id

ID of group

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Adds one or more user to the group

POST /IServ/Core/Entity/Group/{id}/link/users

Tags: IServ Core Group

Returns the updated group

Uses default content-types: application/json

Array of user IDs

string
id

ID of group

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Returns all privileges

GET /IServ/Core/Entity/Privilege

Tags: IServ Core Privilege
extended

Include list of IDs of related entities (if available)

query object

application/json

200 OK

A list of privileges

object
title: string

Title

module: string

Module

groups: string[]

Array of groups

string
roles: string[]

Array of roles

string
_id: string

The internal ID

400 Bad Request

Invalid request

Finds privilege by ID

GET /IServ/Core/Entity/Privilege/{id}

Tags: IServ Core Privilege

Returns a single privilege

id

ID of privilege

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Adds one or more group to the privilege

POST /IServ/Core/Entity/Privilege/{id}/link/groups

Tags: IServ Core Privilege

Returns the updated privilege

Uses default content-types: application/json

Array of group IDs

string
id

ID of privilege

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Adds one or more role to the privilege

POST /IServ/Core/Entity/Privilege/{id}/link/roles

Tags: IServ Core Privilege

Returns the updated privilege

Uses default content-types: application/json

Array of role IDs

string
id

ID of privilege

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Returns all roles

GET /IServ/Core/Entity/Role

Tags: IServ Core Role
extended

Include list of IDs of related entities (if available)

query object

application/json

200 OK

A list of roles

object
name: string

Name

module: string

Module

_id: string

The internal ID

400 Bad Request

Invalid request

Creates a new role

POST /IServ/Core/Entity/Role

Tags: IServ Core Role

Uses default content-types: application/json

Role object to create

application/json

201 Created

Role creation successful

400 Bad Request

Invalid request

Deletes a role

DELETE /IServ/Core/Entity/Role/{id}

Tags: IServ Core Role
id

ID of role

path string

application/json

204 No Content

Operation successful

400 Bad Request

Invalid request

403 Forbidden

The role may not be deleted

404 Not Found

Not found

Finds role by ID

GET /IServ/Core/Entity/Role/{id}

Tags: IServ Core Role

Returns a single role

id

ID of role

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Adds one or more privilege to the role

POST /IServ/Core/Entity/Role/{id}/link/privileges

Tags: IServ Core Role

Returns the updated role

Uses default content-types: application/json

Array of privilege IDs

string
id

ID of role

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Returns all users

GET /IServ/Core/Entity/User

Tags: IServ Core User
extended

Include list of IDs of related entities (if available)

query object

application/json

200 OK

A list of users

object
username: string

Account

firstname: string

First name

lastname: string

Last name

status: string

Status

created: date (date)

Created on

createdBy: string

Created by

lastlogin: datetime (date-time)

Last login

_id: string

The internal ID

400 Bad Request

Invalid request

Creates a new user

POST /IServ/Core/Entity/User

Tags: IServ Core User

Uses default content-types: application/json

User object to create

username: string

Account

firstname: string

First name

lastname: string

Last name

status: string , x ∈ { a , r , i }

Status

type: string

User type

importId: string

Import ID

auxInfo: string

Class/Information

application/json

201 Created

User creation successful

400 Bad Request

Invalid request

Deletes a user

DELETE /IServ/Core/Entity/User/{id}

Tags: IServ Core User
id

ID of user

path string

application/json

204 No Content

Operation successful

400 Bad Request

Invalid request

403 Forbidden

The user may not be deleted

404 Not Found

Not found

Finds user by ID

GET /IServ/Core/Entity/User/{id}

Tags: IServ Core User

Returns a single user

id

ID of user

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Updates user

PUT /IServ/Core/Entity/User/{id}

Tags: IServ Core User

Returns the updated user

Uses default content-types: application/json

Values to update user with - all optional.

username: string

Account

firstname: string

First name

lastname: string

Last name

status: string , x ∈ { a , r , i }

Status

type: string

User type

importId: string

Import ID

auxInfo: string

Class/Information

id

ID of user

path string

application/json

200 OK

Operation successful

username: string

Account

firstname: string

First name

lastname: string

Last name

status: string , x ∈ { a , r , i }

Status

type: string

User type

importId: string

Import ID

auxInfo: string

Class/Information

400 Bad Request

Invalid request

403 Forbidden

The user may not be updated

404 Not Found

Not found

Adds one or more group to the user

POST /IServ/Core/Entity/User/{id}/link/groups

Tags: IServ Core User

Returns the updated user

Uses default content-types: application/json

Array of group IDs

string
id

ID of user

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Adds one or more privilege to the user

POST /IServ/Core/Entity/User/{id}/link/privileges

Tags: IServ Core User

Returns the updated user

Uses default content-types: application/json

Array of privilege IDs

string
id

ID of user

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Adds one or more role to the user

POST /IServ/Core/Entity/User/{id}/link/roles

Tags: IServ Core User

Returns the updated user

Uses default content-types: application/json

Array of role IDs

string
id

ID of user

path string

application/json

200 OK

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Sets the administrator password of the user

POST /IServ/Core/User/{id}/adminpassword

Tags: IServ Core User

Please be aware that this no longer grants immediate access to the admin section. The user needs the admin role (ROLE_ADMIN) in addition.

Uses default content-types: application/json

The new admin password

password: string
"secretpassword"
id

The ID of user

path string

application/json

204 No Content

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Resets the administrator password of the user

POST /IServ/Core/User/{id}/adminpassword/reset

Tags: IServ Core User
id

The ID of user

path string

application/json

200 OK

Returns the temporary administrator password

Example for application/json
{
"password": "123456"
}
password: string
"secretpassword"
400 Bad Request

Invalid request

404 Not Found

Not found

Removes the administrator password from the user

POST /IServ/Core/User/{id}/adminpassword/revoke

Tags: IServ Core User

Please be aware that this removes only the administrator password. The user may still own the admin role (ROLE_ADMIN). Please remove the role, if you'd wish to remove the user's access to the admin section.

id

The ID of user

path string

application/json

204 No Content

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Sets the password of the user

POST /IServ/Core/User/{id}/password

Tags: IServ Core User

Uses default content-types: application/json

The new password

password: string
"secretpassword"
id

The ID of user

path string

application/json

204 No Content

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

Resets the password of the user

POST /IServ/Core/User/{id}/password/reset

Tags: IServ Core User
id

The ID of user

path string

application/json

200 OK

Returns the temporary password

Example for application/json
{
"password": "123456"
}
password: string
"secretpassword"
400 Bad Request

Invalid request

404 Not Found

Not found

Restores a deleted user

POST /IServ/Core/User/{id}/restore

Tags: IServ Core User

A deleted user can be restored until he/she gets automatically purged from the system (see "ActPurge" in iservcfg).

id

The ID of user

path string

application/json

204 No Content

Operation successful

400 Bad Request

Invalid request

404 Not Found

Not found

POST /IServ/Sso/authenticate

Tags: IServ Sso

Returns an authentication token which allows a user to be logged in automatically

username

The user to authenticate

formData string

application/json

200 OK

An authentication token and a returnTo URL

username: string

The authenticated username

token: string

The authentication token

return_to: string

The target URL to redirect the user to

400 Bad Request

Invalid request

Schema definitions

IServ.Core.Group: object

name: string

Name

account: string

Account

home: string

Directory

owner: string

Owner

created: date (date)

Created on

createdBy: string

Created by

deleted: date (date)

Deleted on

deletedBy: string

Deleted by

flags: string[]

Array of group flags

string
users: string[]

Array of members

string
privileges: string[]

Array of privileges

string

IServ.Core.Privilege: object

module: string

Module

description: string

Description

inverted: boolean

Applies to

groups: string[]

Array of groups

string
roles: string[]

Array of roles

string

IServ.Core.Role: object

name: string

Name

module: string

Module

privileges: string[]

Array of privileges

string

IServ.Core.User: object

username: string

Account

firstname: string

First name

lastname: string

Last name

status: string

Status

type: string

Type

auxInfo: string

Class/Information

importId: string

Import ID

created: date (date)

Created on

createdBy: string

Created by

lastlogin: datetime (date-time)

Last login

deleted: date (date)

Deleted on

deletedBy: string

Deleted by

roles: string[]

Array of roles

string
groups: string[]

Array of groups

string
admin: boolean

Administrator

privileges: string[]

Array of privileges

string