Move notifications api docs to dev docs

modules/developer_manual/examples/core/apis/ocs/notifications/delete-user-notification-response.json

@@ -0,0 +1,14 @@
+{
+	"ocs": {
+		...
+		"data": {
+			...
+			"capabilities": {
+				...
+				"notifications": {
+					"ocs-endpoints": ["list", "get", "delete"]
+				}
+			}
+		}
+	}
+}

modules/developer_manual/examples/core/apis/ocs/notifications/get-server-capabilities-response.json

@@ -0,0 +1,15 @@
+{
+    "ocs": {
+        "data": {
+            "capabilities": {
+                "notifications": {
+                    "ocs-endpoints": [
+                        "list",
+                        "get",
+                        "delete"
+                    ]
+                }
+            }
+        }
+    }
+}

modules/developer_manual/examples/core/apis/ocs/notifications/get-server-capabilities-response.xml

@@ -0,0 +1,16 @@
+<?xml version="1.0"?>
+<ocs>
+    <!-- remainder of the response -->
+    <data>
+        <!-- remainder of the data element -->
+        <capabilities>
+            <notifications>
+                <ocs-endpoints>
+                    <element>list</element>
+                    <element>get</element>
+                    <element>delete</element>
+                </ocs-endpoints>
+            </notifications>
+        </capabilities>
+    </data>
+</ocs>

modules/developer_manual/examples/core/apis/ocs/notifications/get-user-notifications-no-notifications-response.json

@@ -0,0 +1,12 @@
+{
+  "ocs": {
+    "meta": {
+      "status": "ok",
+      "statuscode": 200,
+      "message": null,
+      "totalitems": "",
+      "itemsperpage": ""
+    },
+    "data": []
+  }
+}

modules/developer_manual/examples/core/apis/ocs/notifications/get-user-notifications-response.json

@@ -0,0 +1,31 @@
+{
+	"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",
+			"message": "",
+			"link": "http://localhost/index.php/apps/files_sharing/pending",
+			"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
+			}]
+		}]
+	}
+}

modules/developer_manual/examples/core/scripts/curl/ocs/notifications/get-server-capabilities.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+USERNAME=admin
+PASSWORD={oc-examples-password}
+API_PATH="ocs/v2.php/cloud/capabilities"
+SERVER_URI="{oc-examples-server-url}"
+
+# Get server capabilities in XML format
+curl '$SERVER_URI/$API_PATH/' \
+  --user "${USERNAME}:${PASSWORD}"
+
+# Get server capabilities in JSON format
+curl '$SERVER_URI/$API_PATH?format=json' \
+  --user "${USERNAME}:${PASSWORD}" | jq

modules/developer_manual/examples/core/scripts/curl/ocs/notifications/get-user-notifications.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+USERNAME=admin
+PASSWORD={oc-examples-password}
+API_PATH="ocs/v2.php/apps/notifications/api/v1/notifications"
+SERVER_URI="{oc-examples-server-url}"
+
+# Get response in XML format
+curl '$SERVER_URI/$API_PATH/' \
+  --user "${USERNAME}:${PASSWORD}"
+
+# Get response in JSON format
+curl '$SERVER_URI/$API_PATH?format=json' \
+  --user "${USERNAME}:${PASSWORD}" | jq
+

modules/developer_manual/nav.adoc

@@ -22,6 +22,7 @@
 *** xref:core/apis/index.adoc[Available APIs]
 **** xref:core/apis/externalapi.adoc[The External API]
 **** OCS
+***** xref:core/apis/ocs/notifications/ocs-endpoint-v1.adoc[The OCS Notifications API (v1)]
 ***** xref:core/apis/ocs-capabilities.adoc[The OCS REST API]
 ***** xref:core/apis/ocs-recipient-api.adoc[The OCS Recipient API]
 ***** xref:core/apis/ocs-share-api.adoc[The OCS Share API]

modules/developer_manual/pages/app/advanced/notifications.adoc

@@ -1,8 +1,191 @@
 = Notifications
 
-In this document, you can learn how to send notifications in apps.
+In this document, you can learn how to:
 
-== Sending Notifications
+* xref:create-a-new-notification[Create a notification]
+* xref:mark-a-notification[Mark a notification]
+* xref:prepare-a-notification-for-display[Prepare a notification for display]
+* xref:send-notifications[Send notifications]
+
+== Create a New Notification
+
+To create a new notification requires the following steps:
+
+. xref:retrieve-new-notification-object[Retrieve a new notification object from the notification manager]
+. xref:set-the-necessary-information-for-the-notification[Set the necessary notification information]
+. xref:send-the-notification-back-to-the-manager[Send the notification back to the manager]
+
+[[retrieve-new-notification-object]]
+=== Retrieve a New Notification Object From the Notification Manager
+
+Grab a new notification object (`\OCP\Notification\INotification`) from the manager (`\OCP\Notification\IManager`). 
+
+[source,php]
+----
+<?php
+
+$manager = \OC::$server->getNotificationManager();
+$notification = $manager->createNotification();
+----
+
+=== Set the Necessary Information for the Notification
+
+[source,php]
+----
+<?php
+
+$acceptAction = $notification\->createAction();
+$acceptAction
+  ->setLabel('accept')
+  ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'POST');
+
+$declineAction = $notification->createAction();
+$declineAction->setLabel('decline')
+    ->setLink('/apps/files_sharing/api/v1/remote_shares/1337', 'DELETE');
+
+$notification->setApp('files_sharing')
+    ->setUser('recipient1')
+    ->setDateTime(new DateTime())
+    ->setObject('remote', '1337') // $type and $id
+    ->setSubject('remote_share', ['/fancyFolder']) // $subject and $parameters
+    ->addAction($acceptAction)
+    ->addAction($declineAction)
+;
+----
+
+TIP: Setting _app_, _user_, _timestamp_, _object_ and _subject_ are mandatory.
+
+You should not use a translated _subject_, _message_ or _action label_.
+Use something like a "_language key_", to avoid length problems with translations in the storage of a notification app.
+Translation is done via invocation of your notifier by the manager when the notification is prepared for display.
+
+=== Send the Notification Back to the Manager
+
+[source,php]
+----
+<?php
+
+$manager->notify($notification);
+
+----
+== Mark a Notification
+
+If the user accepted the share or the share was removed/unshared, we want to remove the notification, because no user action is needed anymore.
+To do this, we simply have to call the `markProcessed()` method on the manager with the necessary information on a notification object:
+
+[source,php]
+----
+<?php
+
+$manager = \OC::$server->getNotificationManager();
+$notification
+  ->setApp('files_sharing')
+  ->setObject('remote', 1337)
+  ->setUser('recipient1');
+$manager->markProcessed($notification);
+----
+
+Only the app name is mandatory, so if you don't set the user, the notification will be marked as processed for all users that have it.
+
+The following example shows how to mark all notifications for the `files_sharing` app on the object "_remote #1337_" as processed.
+
+[source,php]
+----
+<?php
+
+$manager = \OC::$server->getNotificationManager();
+$notification
+  ->setApp('files_sharing')
+  ->setObject('remote', 1337);
+$manager->markProcessed($notification);
+----
+
+Notifications can be marked as _read_, _deleted_, _processed_, or _obsoleted_.
+To 
+
+
+== Prepare a Notification for Display
+
+To prepare a notification for display, in `app.php`, register your Notifier (`\OCP\Notification\INotifier`) interface to the manager,  using a `\Closure`.
+
+[source,php]
+----
+<?php
+
+$manager = \OC::$server->getNotificationManager();
+$manager->registerNotifier(function() {    
+  return new \OCA\Files_Sharing\Notifier(\OC::$server->getL10NFactory());
+});
+----
+
+The manager will execute the closure and then call the `prepare()` method on your notifier.
+If the notification is not known by your app, throw an `\InvalidArgumentException`. 
+However, if it is actually from your app, you must set the parsed _subject_, _message_, and _action_ labels.
+
+[source,php]
+----
+<?php
+
+protected $factory;
+
+public function __construct(\OCP\L10N\IFactory $factory) {
+    $this->factory = $factory;
+}
+
+/**
+ * @param INotification $notification
+ * @param string $languageCode The code of the language that should be used to prepare the notification
+ */
+public function prepare(INotification $notification, $languageCode) {
+    if ($notification->getApp() !== 'files_sharing') {
+        // Not my app => throw
+        throw new \InvalidArgumentException();
+    }
+
+    // Read the language from the notification
+    $l = $this->factory->get('myapp', $languageCode);
+
+    switch ($notification->getSubject()) {
+        // Deal with known subjects
+        case 'remote_share':
+            $notification->setParsedSubject(
+                (string) $l->t(
+                  'You received the remote share "%s"', 
+                  $notification->getSubjectParameters()
+                )
+            );
+
+            // Deal with the actions for a known subject
+            foreach ($notification->getActions() as $action) {
+                switch ($action->getLabel()) {
+                    case 'accept':
+                        $action->setParsedLabel(
+                            (string) $l->t('Accept')
+                        );
+                    break;
+
+                    case 'decline':
+                        $action->setParsedLabel(
+                            (string) $l->t('Decline')
+                        );
+                    break;
+                }
+
+                $notification->addParsedAction($action);
+            }
+            return $notification;
+        break;
+
+        default:
+            // Unknown subject => Unknown notification => throw
+            throw new \InvalidArgumentException();
+    }
+}
+----
+
+NOTE: Currently, no markup is allowed.
+
+== Send Notifications
 
 To send notifications from your app, requires four steps, these are:
 

modules/developer_manual/pages/core/apis/ocs/notifications/index.adoc

@@ -0,0 +1,6 @@
+= Notifications API
+
+In this section you will information on ownCloud’s Notifications API, including:
+
+* xref:core/apis/ocs/notifications/notification-workflow.adoc[The notification workflow]
+* xref:core/apis/ocs/notifications/ocs-endpoint-v1.adoc[The OCS API Endpoint (v1)]