[Documentation] Clarify usage of Activity filters

[aaronsegura]

Using /:filter returns 404. Must use /filter without the colon.

Signed-off-by: Aaron Segura <aaron@aaronsegura.com>

[nickvergessen]

What was actually meant is that filter is a parameter:

Suggested change

	GET /ocs/v2.php/apps/activity/api/v2/activity/filter
	GET /ocs/v2.php/apps/activity/api/v2/activity/{filter}

https://github.com/nextcloud/activity/blob/master/appinfo/routes.php#L28

[aaronsegura]

How would that translate into a curl command? I'm only able to successfully filter using the syntax I originally submitted:

$ curl -u admin:admin -H "OCS-APIRequest: true" 'http://localhost:8181/ocs/v2.php/apps/activity/api/v2/activity/filter?since=0&limit=1&object_type=files&object_id=30&format=json'
{"ocs":{"meta":{"status":"ok","statuscode":200,"message":"OK"},"data":[{"activity_id":43,"app":"files_sharing","type":"shared","user":"admin","subject":"Shared with Test User","subject_rich":["Shared with {user}",{"file":{"type":"file","id":"30","name":"Nextcloud Manual.pdf","path":"Nextcloud Manual.pdf","link":"http:\/\/localhost:8181\/f\/30"},"user":{"type":"user","id":"testuser","name":"Test User"}}],"message":"","message_rich":["",[]],"object_type":"files","object_id":30,"object_name":"\/Nextcloud Manual.pdf","objects":{"30":"\/Nextcloud Manual.pdf"},"link":"http:\/\/localhost:8181\/apps\/files\/?dir=\/","icon":"http:\/\/localhost:8181\/core\/img\/actions\/share.svg","datetime":"2022-06-24T18:11:11+00:00"}]}}

^This returns proper results filtered for the given file ID. Anything else I've tried either returns the latest activity without filtering or a 404.

[nickvergessen]

I just noticed the confusion.

https://github.com/nextcloud/activity/blob/master/appinfo/routes.php#L27
There is a filters endpoint which gives you valid {filter} values back, but that API endpoint seems to not be documented.

Sample response from my dev setup:

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": "OK"
    },
    "data": [
      {
        "id": "all",
        "name": "All activities",
        "icon": "https://nextcloud25.local/appspackaged/activity/img/activity-dark.svg",
        "priority": 0
      },
      {
        "id": "self",
        "name": "By you",
        "icon": "https://nextcloud25.local/core/img/actions/user.svg",
        "priority": 1
      },
      {
        "id": "by",
        "name": "By others",
        "icon": "https://nextcloud25.local/core/img/places/contacts.svg",
        "priority": 2
      },
      {
        "id": "files_favorites",
        "name": "Favorites",
        "icon": "https://nextcloud25.local/core/img/actions/star-dark.svg",
        "priority": 10
      },
      {
        "id": "files",
        "name": "File changes",
        "icon": "https://nextcloud25.local/core/img/places/files.svg",
        "priority": 30
      },
      {
        "id": "security",
        "name": "Security",
        "icon": "https://nextcloud25.local/core/img/actions/password.svg",
        "priority": 30
      },
      {
        "id": "files_sharing",
        "name": "File shares",
        "icon": "https://nextcloud25.local/core/img/actions/share.svg",
        "priority": 31
      },
      {
        "id": "calendar",
        "name": "Calendar",
        "icon": "https://nextcloud25.local/core/img/places/calendar.svg",
        "priority": 40
      },
      {
        "id": "calendar_todo",
        "name": "To-dos",
        "icon": "https://nextcloud25.local/core/img/actions/checkmark.svg",
        "priority": 40
      },
      {
        "id": "comments",
        "name": "Comments",
        "icon": "https://nextcloud25.local/core/img/actions/comment.svg",
        "priority": 40
      },
      {
        "id": "contacts",
        "name": "Contacts",
        "icon": "https://nextcloud25.local/core/img/places/contacts.svg",
        "priority": 40
      }
    ]
  }
}

[aaronsegura]

I think I have found the source of my confusion.

Is it intended that users are allowed to filter by object_id/object_type when using a type filter from the filters endpoint? The object_id/object_type arguments are only respected when I use the literal string filter as the type filter.

From lib/Data.php:

if ($filter === 'self') {
        $query->andWhere($query->expr()->eq('user', $query->createNamedParameter($user)));
} elseif ($filter === 'by') {
        $query->andWhere($query->expr()->neq('user', $query->createNamedParameter($user)));
} elseif ($filter === 'filter') {
        $query->andWhere($query->expr()->eq('object_type', $query->createNamedParameter($objectType)));
        $query->andWhere($query->expr()->eq('object_id', $query->createNamedParameter($objectId)));
}

My assumption was that object_id/object_type arguments should cause results to be filtered to the specific object_id/object_type no matter which type filter is provided. Is that not the case? Should I open an issue to have this corrected, or is it intended behavior?

[nickvergessen]

Is that not the case?

No, because it didn't have any usecase yet. the filter filter is used in the right sidebar of the files app. The other filters are the left sidebar when you open the activity app. So so far this is intended behaviour.
I can try to complete the docs if you are too confused for now.

[aaronsegura]

Nope, not confused any more. I have updated my PR to reflect the intended behavior now that you've confirmed that's what was actually intended.