Operations#

This section cover creating, retrieving and updating operations via API endpoints.

Deleting operations is not allowed. They can only be marked as archived.

Each operation must have an non-empty title. The end-timestamp must not be before the start-timestamp.

Create operation#

In order to create an operation, the operation.create permission is needed. Creating an operation is done by calling:

POST /operations

{
    "title": "<operation_title>",
    "description": "<description>"
    "start": "2006-01-02T15:04:05Z07:00",
    "end": "2006-01-02T15:04:05Z07:00",
    "is_archived": false
}

The end-field is optional.

Response (201):

{
    "id": "<assigned_id>",
    "title": "<operation_title>",
    "description": "<description>"
    "start": "2006-01-02T15:04:05Z07:00",
    "end": "2006-01-02T15:04:05Z07:00",
    "is_archived": false
}

Update operation#

Updating an operation requires the operation.update permission. If provided, updating is done via:

PUT /operations/<operation_id>

{
    "id": "<operation_id",
    "title": "<operation_title>",
    "description": "<description>"
    "start": "2006-01-02T15:04:05Z07:00",
    "end": "2006-01-02T15:04:05Z07:00",
    "is_archived": false
}

Retrieve operations#

Retrieving an operation by its id is possible via:

GET /operations/<operation_id>

Response (200):

{
    "id": "<operation_id",
    "title": "<operation_title>",
    "description": "<description>"
    "start": "2006-01-02T15:04:05Z07:00",
    "end": "2006-01-02T15:04:05Z07:00",
    "is_archived": false
}

Retrieving a paginated operation list requires the operation.view.any permission, if all operations should be retrieved. Otherwise, only operations are returned that the requesting client is member of.

GET /operations

Entry payload:

{
    "id": "<operation_id",
    "title": "<operation_title>",
    "description": "<description>"
    "start": "2006-01-02T15:04:05Z07:00",
    "end": "2006-01-02T15:04:05Z07:00",
    "is_archived": false
}

Available query parameters for filtering:

  • only_ongoing (default: false): Excludes all operations not currently ongoing. This includes operations not having an end-timestamp set or being in the future.

  • include_archived (default: false): Includes archived operations.

  • for_user: Includes only operations the user with the given ID is member of.

The following fields can be used for ordering:

  • title

  • description

  • start

  • end

  • is_archived

Search is available via:

GET /operations/search

Entry payload:

{
    "id": "<operation_id",
    "title": "<operation_title>",
    "description": "<description>"
    "start": "2006-01-02T15:04:05Z07:00",
    "end": "2006-01-02T15:04:05Z07:00",
    "is_archived": false
}

The search index can be rebuilt via:

POST /operations/search/rebuild

Update operation members#

Updating operation members requires the operation.members.update permission:

PUT /operations/<operation_id>/members

[
    "<user_id_1>",
    "<user_id_2>",
    "<user_id_n>"
]

Retrieve operation members#

Retrieving a paginated member list requires the operation.members.view permission and is done via:

GET /operations/<operation_id>/members

Entry payload:

{
    "id": "<user_id>",
    "username": "<username>",
    "first_name": "<first_name>",
    "last_name": "<last_name>",
    "is_active": true
}

The following fields can be used for ordering:

  • username

  • first_name

  • last_name