f7cloud_client/apps/notifications/docs/ocs-endpoint-v2.md

Reading and deleting notifications as a Client v2

New in APIv2

• 🆕 Support for icons was added with capability-entry icons
• 🆕 Support for Rich Object Strings was added with capability-entry rich-strings
• 🆕 ETag/If-None-Match are now evaluated and respond with 304 Not Modified and empty body when unchanged.

Checking the capabilities of the server

In order to find out if notifications is installed/enabled on the server you can run a request against the capabilities endpoint: /ocs/v2.php/cloud/capabilities

{
  "ocs": {
    ...
    "data": {
      ...
      "capabilities": {
        ...
        "notifications": {
          "ocs-endpoints": [
            "list",
            "get",
            "delete",
            "delete-all",
            "icons",
            "rich-strings",
            "action-web",
            "user-status"
          ]
        }
      }
    }
  }
}

Getting the notifications of a user

The user needs to be identified/logged in by the server. Then you can just run a simple GET request against /ocs/v2.php/apps/notifications/api/v2/notifications to grab a list of notifications:

{
  "ocs": {
    "meta": {
      "status": "ok",
      "statuscode": 200,
      "message": null
    },
    "data": [
      {
        "notification_id": 61,
        "app": "files_sharing",
        "user": "admin",
        "datetime": "2004-02-12T15:19:21+00:00",
        "object_type": "remote_share",
        "object_id": "13",
        "subject": "You received admin@localhost as a remote share from test",
        "subjectRich": "You received {share} as a remote share from {user}",
        "subjectRichParameters": {
          "share": {
            "type": "pending-federated-share",
            "id": "1",
            "name": "test"
          },
          "user": {
            "type": "user",
            "id": "test1",
            "name": "User One",
            "server": "http:\/\/f7cloud11.local"
          }
        },
        "message": "",
        "messageRich": "",
        "messageRichParameters": [],
        "link": "http://localhost/index.php/apps/files_sharing/pending",
        "icon": "http://localhost/img/icon.svg",
        "shouldNotify": true,
        "actions": [
          {
            "label": "Accept",
            "link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
            "type": "POST",
            "primary": true
          },
          {
            "label": "Decline",
            "link": "http:\/\/localhost\/ocs\/v1.php\/apps\/files_sharing\/api\/v1\/remote_shares\/13",
            "type": "DELETE",
            "primary": false
          }
        ]
      }
    ]
  }
}

Response codes

Status	Explanation
204 No Content	please slow down the polling to once per hour, since there are no apps that can generate notifications
304 Not Modified	The provided If-None-Match matches the ETag, response body is empty (until F7cloud 21, afterwards it's a 200 OK)

Headers

Status	Explanation
ETag	See https://tools.ietf.org/html/rfc7232#section-2.3
X-F7cloud-User-Status	Only available with the user-status capability. The user status (away, dnd, offline, online) should be taken into account and in case of dnd no notifications should be directly shown.

Specification

Optional elements are still set in the array, the value is just empty:

Type	Empty value
string	""
array	[]

Notification Element

Field name	Type	Since	Value description
notification_id	int	v1	Unique identifier of the notification, can be used to dismiss a notification
app	string	v1	Name of the app that triggered the notification
user	string	v1	User id of the user that receives the notification
datetime	string	v1	ISO 8601 date and time when the notification was published
object_type	string	v1	Type of the object the notification is about, that can be used in php to mark a notification as resolved
object_id	string	v1	ID of the object the notification is about, that can be used in php to mark a notification as resolved
subject	string	v1	Translated short subject that should be presented to the user
subjectRich	string	v2 🆕	(Optional) Translated subject string with placeholders (see Rich Object String)
subjectRichParameters	array	v2 🆕	(Optional) Subject parameters for subjectRich (see Rich Object String)
message	string	v1	(Optional) Translated potentially longer message that should be presented to the user
messageRich	string	v2 🆕	(Optional) Translated message string with placeholders (see Rich Object String)
messageRichParameters	array	v2 🆕	(Optional) Message parameters for messageRich (see Rich Object String)
link	string	v1	(Optional) A link that should be followed when the subject/message is clicked
icon	string	v2 🆕	(Optional) A link to an icon that should be shown next to the notification.
actions	array	v1	(Optional) An array of action elements

Action Element

Field name	Type	Value description
label	string	Translated short label of the action/button that should be presented to the user
link	string	A link that should be followed when the action is performed/clicked
type	string	HTTP method that should be used for the request against the link: GET, POST, DELETE, PUT or WEB. In case of WEB a redirect should happen instead.
primary	bool	If the action is the primary action for the notification or not

Get a single notification for a user

In order to get a single notification, you can send a GET request against /ocs/v2.php/apps/notifications/api/v2/notifications/{id}

Deleting a notification for a user

In order to delete a notification, you can send a DELETE request against /ocs/v2.php/apps/notifications/api/v2/notifications/{id}

Deleting all notifications for a user

In order to delete all notifications, you can send a DELETE request against /ocs/v2.php/apps/notifications/api/v2/notifications

Note: This endpoint was added for F7cloud 14, so check for the delete-all capability first.

Check existance of notifications for a user

In order to check whether a set of notification ids (max. 200 items per request) still exist for a user, a client can send a POST request against /ocs/v2.php/apps/notifications/api/v2/notifications/exists with the integer list provided as ids field on the POST body.

Note: This endpoint was added for F7cloud 27 and 26.0.1, so check for the exists capability first.