[ocis+web] activity: design API

[tbsbdr]

Description

User Stories

• As an ocis client application developer, I want an efficient search API for activities, so that I can query activities for certain contexts

• As an ocis client application developer, I want an efficient search API for activities, so that I can build a personalized kind of "what happened in my ownCloud" page for users

• As an ocis client application developer, I expect the activity search API to respect the KQL format like for file search so that I can reuse my already existing search ui implementation

Value

Make activity available for client applications.

Acceptance Criteria

• activity search query syntax is KQL (like for file search)
  • resourceID:12345 depth:-1 limit:1000
• it should be possible to set a limit (e.g. 1000 items)
• pagination would be nice, but is optional
• filters for the first iteration are:
  • resourceID: to limit an activity search to a file, folder, share or space root (ALL my accessible files / folders / shares / spaces if no resourceID is set, but we can make this resourceID required in the first iteration if that makes things easier)
  • depth (default -1): include all subfolders of the given fileId if set to -1.
  • activity types (optional): limit the search to certain activity types (see Event types in [web] Show Activities (text only) web#10800) (to be discussed... not needed for MVP but one of the next requirements after MVP)
• if the user who makes the search request doesn't have the permission to see activities, early return with an error response (403?)
• graph https://learn.microsoft.com/en-us/graph/microsoft-graph-activity-logs-overview

This issue should be solved in two steps:

• 1: design API, at least include client devs from the web ui, to be decided by @tbsbdr if other client teams should join as well. As an outcome, client teams can work with mock data to start the client implementation. The API design is this expected outcome of this issue.
• 2: implement the API, tracked via [ocis] implement "activity" api #9196

Definition of ready

• Everybody needs to understand the value written in the user story
• Acceptance criteria have to be defined
• All dependencies of the user story need to be identified
• Feature should be seen from an end user perspective
• Story has to be estimated
• Story points need to be less than 20

Definition of done

• Functional requirements
  • Functionality described in the user story works
  • Acceptance criteria are fulfilled
• Quality
  • Code review happened
  • CI is green (that includes new and existing automated tests)
  • Critical code received unit tests by the developer
• Non-functional requirements
  • No sonar cloud issues
• Configuration changes
  • The next branch of the ocis charts is compatible

Visual

[kulmann]

From what I currently have in my mind, this is a search api in every situation. Please involve me in concepting if possible. 🙈

This issue shows some requirements for the API: owncloud/web#10800

[fschade]

MS-Graph docs

• https://learn.microsoft.com/en-us/graph/api/activities-list?view=graph-rest-beta
• https://learn.microsoft.com/en-us/graph/api/resources/itemactivity?view=graph-rest-beta

Activity type mapping oCIS <-> MS-Graph

• added (ms action name: create)
  • postprocessing-finished (ms action name: does not exist)
  • folder-created (ms action name: does not exist)
  • file-touched (ms action name: does not exist)
• item-trashed (ms action name: delete)
• item-moved (ms action name: move)
• item-renamed (ms action name: rename)
• share
  • share-created (ms action name: does not exist, only general share exists)
  • share-removed (ms action name: does not exist, only general share exists)
  • link-created (ms action name: does not exist, only general share exists)
  • link-removed (ms action name: does not exist, only general share exists)
  • space-member-added (ms action name: does not exist, only general share exists)
  • space-member-removed (ms action name: does not exist, only general share exists)
• (TBD) Unauthenticated download (ms action name: does not exist)

oCIS graph-api endpoints

• GET /drives/{drive-id}/activities (redirect to /drives/{drive-id}/items/{drive-id}/activities)
• GET /drives/{drive-id}/items/{item-id}/activities

Request

• headers
  • Accept-Language: e,g, en-US
• urls params
  • drive-id
  • item-id
• query params
  • limit: e.g. limit=999
  • query (kql): e.g. depth:1
    • depth: default -1

Response

{
	"value": [
		{
			"id": "5380e156-d65e-4024-9691-0f0c1f2796e4",
			"action": {
				"delete": {
					"name": "some resource name",
					"objectType": "folder"
				}
			},
			"driveItem": {
				"id": "7f92b0a9-06ad-49dc-890f-0e0a6eb4dea6$e9f01ca3-577f-4d1d-acd4-1cc44149ac25!5fb9f87c-a317-467b-9882-eb9f171564ac"
			},
			"actor": {
				"user": {
					"id": "31c63047-b271-45bf-82fd-7aa597fb08a8",
					"displayName": "Albert Einstein"
				}
			},
			"times": {
				"recordedTime": "2017-07-29T18:34:40Z"
			},
			"@template": {
				"message": "{user} deleted {resource}.",
				"variables": {
					"user": {
						"id": "71f9de60-8b24-4cfe-9378-87d47aef0d04",
						"displayName": "Marie Curie"
					},
					"resource": {
						"id": "7f92b0a9-06ad-49dc-890f-0e0a6eb4dea6$e9f01ca3-577f-4d1d-acd4-1cc44149ac25!5fb9f87c-a317-467b-9882-eb9f171564ac",
						"name": "some folder name"
					}
				}
			}
		}
	]
}

Topics

• We can only create multiple activities for a resource that is shared with multiple individuals.
  Grouping as shown in the mock is not easily possible.
• Item restore is not mentioned in the ticket, microsoft has a dedicated event for that.
  Should we consider that too, and if yes, should we add it to the added events or to the restore events?
• In oCIS we do not differentiate between file-edit and file-added, therefore, we are not able to render the
  message for that differently, e.g. Albert Einstein edited some file.
• Unauthenticated download activity is not part of the MVP.
• Getting activities for all spaces is not part of the MVP.
• Should we create a new activities service or make it part of the existing graph service?

[butonic]

hm ... the ms graph api also has an endpoint for a user activity stream:

• https://learn.microsoft.com/en-us/graph/api/resources/activity-feed-api-overview?view=graph-rest-beta
• https://learn.microsoft.com/en-us/graph/api/resources/projectrome-activity?view=graph-rest-beta

The activity feed is a dedicated stream that can be fed by any application. It is part of Project Rome in case that rings a bell.

It seems to me that endpoints is more user centric.

Hm but the drives activities endpoints might scale better because we don't have to write a history event for every user.

[micbar]

adding @kulmann here because he has more requirements for the KQL part, especially time ranges.

[AlexAndBear]

The kql part for the MVP is kind of minimal or even not existent.
Anyways the KQL query is just a string we send as query parameter and should not have a big impact on the API specification.

[kobergj]

hm ... the ms graph api also has an endpoint for a user activity stream:

Doesn't seem to be what we are looking for. This is about getting the activities on a user. Answering questions like "What have I done?" or "What has this user done?". We are looking for the activities on a resource. Answering questions like "What happened while I was on holidays?". These are two completely different things.

[micbar]

Done in ADR and in owncloud/libre-graph-api#184