API docs by Redocly

SPI IHK content provider for examination (1.0)

Download OpenAPI specification:

License: Apache-2.0

This is an examination API for IHK content service provider.

OneTimePassword

Create several one-time passwords

Generate one or more one-time passwords for accessing a specific examination A one-time password (otp) can be used to access a examination content or to perform actions related to it. Each OTP is associated with a specific content and subject (user). The content is identified by a content_id and normally is unique for each examination and profession.

Authorizations:
bearerAuth
Request Body schema: application/json
Array
content_id
required
string

Identifier for the examination content

subject_id
required
string

Identifier for the subject or user to which the OTP is issued

additionaltime
string <duration>
Default: "PT0S"

Optional additional time in ISO 8601 duration format this participation has during execution

object (Participation)
object (Participant)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "otp_id": "4g7a07i54",
  • "otp_type": "tan",
  • "content_id": "123456789012345678",
  • "subject_id": "876543210987654321",
  • "duration": "PT15M",
  • "additionaltime": "PT15M",
  • "otpstatus": "created",
  • "expiration": "2019-08-24T14:15:22Z",
  • "participation_id": "participation-1234567890"
}

HandleState

Get current examination status

Retrieve the current status of one or more examinations identified by their OTP IDs. post is used to retrieve the status of multiple examinations at once.

Authorizations:
bearerAuth
Request Body schema: application/json
Array
string

List of otp_id for which to retrieve the status

Responses

Request samples

Content type
application/json
[
  • "123456789012345678"
]

Response samples

Content type
application/json
[
  • {
    }
]

Handle locks and suspensions of examinations

Lock or unlock a list of examinations to prohibit the usage by the participants. The state transitions follow this table: | Current State | Lock State | New State | |---------------|------------|----------| | created | lock | created | | created | unlock | runnable | | runnable | lock | runnable | | runnable | unlock | running* | | running | lock | suspended| | running | unlock | running | | suspended | lock | suspended| | suspended | unlock | running |

  • Note: Unlocking from 'runnable' to 'running' is not triggered by the management system, but by the participant when they start the examination. It will be transmitted by the spi via the monitoring endpoint.
Authorizations:
bearerAuth
path Parameters
lock_state
required
string
Enum: "lock" "unlock"

State to set for the examinations. Use 'lock' to lock and 'unlock' to unlock.

Request Body schema: application/json
Array
string

List of otp_id for which should be locked or unlocked

Responses

Request samples

Content type
application/json
[
  • "123456789012345678"
]

Response samples

Content type
application/json
{
  • "otp_id": "string",
  • "status": "created",
  • "last_updated": "2019-08-24T14:15:22Z"
}

Add additional time to examinations

Adds time a list of examinations. This endpoint allows to add additional time to the examinations identified by their OTP IDs.

Authorizations:
bearerAuth
Request Body schema: application/json
Array
otp_id
required
string

Unique identifier for the one-time password

additionaltime
required
string <duration>

Additional time to add to the examination in ISO 8601 duration format

reason
string

Reason for adding additional time

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "otp_id": "string",
  • "status": "created",
  • "last_updated": "2019-08-24T14:15:22Z"
}

ServerSentEvents

Subscribe for monitoring

Subscribe for monitoring events. These events are sent as Server-Sent Events (SSE) stream. The client will receive a continuous stream of events related to the examination status. The client must provide a valid subscription_id as a query parameter to receive the events.

Authorizations:
bearerAuth
query Parameters
subscription_id
required
string <uuid>
Example: subscription_id=123e4567-e89b-12d3-a456-426614174002

Unique identifier for the subscription

Responses

Response samples

Content type
application/json
{
  • "code": 13,
  • "message": "This or that went wrong"
}

ExecutionEntries

Get all entries made during completed executions

Retrieve all entries (e.g., answers, actions, logs) made by participants during examination executions that are completed. Accepts a list of otp_id.

Authorizations:
bearerAuth
Request Body schema: application/json
Array
string

Responses

Request samples

Content type
application/json
[
  • "4g7a07i54",
  • "7h8b09j65"
]

Response samples

Content type
application/json
{
  • "property1": [
    ],
  • "property2": [
    ]
}