Beschreibung der API¶

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