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.

Bemerkung

Die hier beschriebene Funktionalität wird nur noch für Bestandskunden übergangsweise angeboten. Für seit Juni 2022 installierte Server besteht die Möglichkeit zur Nutzung der veralteten API nicht mehr. Bitte verwenden Sie in diesem Fall die API des IDMs.

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

IServ.Core.Group

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

Removes one or more groupflag from the group

DELETE /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

IServ.Core.Group

400 Bad Request

Invalid request

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

IServ.Core.Group

400 Bad Request

Invalid request

404 Not Found

Not found

Removes one or more privilege from the group

DELETE /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

IServ.Core.Group

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

IServ.Core.Group

400 Bad Request

Invalid request

404 Not Found

Not found

Removes one or more user from the group

DELETE /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

IServ.Core.Group

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

IServ.Core.Group

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

IServ.Core.Privilege

400 Bad Request

Invalid request

404 Not Found

Not found

Removes one or more group from the privilege

DELETE /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

IServ.Core.Privilege

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

IServ.Core.Privilege

400 Bad Request

Invalid request

404 Not Found

Not found

Removes one or more role from the privilege

DELETE /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

IServ.Core.Privilege

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

IServ.Core.Privilege

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

IServ.Core.Role

400 Bad Request

Invalid request

404 Not Found

Not found

Removes one or more privilege from the role

DELETE /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

IServ.Core.Role

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

IServ.Core.Role

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

IServ.Core.User

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

Removes one or more group from the user

DELETE /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

IServ.Core.User

400 Bad Request

Invalid request

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

IServ.Core.User

400 Bad Request

Invalid request

404 Not Found

Not found

Removes one or more privilege from the user

DELETE /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

IServ.Core.User

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

IServ.Core.User

400 Bad Request

Invalid request

404 Not Found

Not found

Removes one or more role from the user

DELETE /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

IServ.Core.User

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

IServ.Core.User

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