# /api/notifications

# Attributes

**title**: Notification title.

**author**: The user who created the notification.

**action**: Notification action

**subject**: Notification subject

**link:**: An HTTP link to the resource involved in the notification.

**target:** Array of notification recipient like :

    target: [{
        objectType: string
        id: string
    }, {...} ]

Where `objectType` is `user` or `community`.

**level**: The notification level: transient, persistant, information.

**read**: The notification has been read by the recipient.

**created_at**: When the notification has been created (default is Date.now())

**data**: Notification specific data. Each notification handler may be able to get data and provide a way to handle/process this data.

# Use case

An external application may be able to publish notifications into the platform in order to notify users about current state.

1. User A launches the external application
2. User A authenticate the external application using OpenPaaS authentication mechanism
3. User A creates a resource on the external application. The user wants to notify other users about this new resource.
4. The application sends a notification to OpenPaaS like:


    {
      "title": "New form",
      "action": "created",
      "object": "form",
      "link": "http://localhost:3000/form/123456789",
      "level": "transient",
      "target": [{objectType: "user", id: "userB"}, {objectType: "user", id: "userC"}, {objectType: "user", id: "userD"}]
    }

Which means that current logged in user created a form which is available on http://localhost:3000/form/123456789.
Users B, C and D will receive the notification (up to the platform to deliver the notification the right way).

## POST /api/notifications

Publish a new notification. If the target contains multiple elements, the platform will create as many notification as there are elements in the array plus the initial one.

**Request Headers:**

- Accept: application/json

**Request Body:**

A notification as JSON. The target is an array of notification recipient.

**Response Headers:**

- Content-Length: Document size

**Status Codes:**

- 201 Created. The body contains the array of created notifications.

**Request:**

    POST /api/notifications
    Accept: application/json
    Host: localhost:8080
    
    {
      title: 'My notification',
      action: 'create',
      object: 'form',
      link: 'http://localhost:8888',
      author: 53a946c41f6d7a5d729e0477,
      target: [ {objectType: 'user', id: 53a946c41f6d7a5d729e0478}, {objectType: 'user', id: 53a946c41f6d7a5d729e0479} ],
      read: false,
      timestamps: { creation: Tue Jun 24 2014 11:37:08 GMT+0200 (CEST) },
      level: 'info'
    }

**Response:**

    HTTP/1.1 201 Created
    [
      {
        title: 'My notification',
        action: 'create',
        object: 'form',
        link: 'http://localhost:8888',
        author: 53a946c41f6d7a5d729e0477,
        _id: 53a946c41f6d7a5d729e047f,
        __v: 0,
        target: [ {objectType: 'user', id: 53a946c41f6d7a5d729e0478}, {objectType: 'user', id: 53a946c41f6d7a5d729e0479} ],
        read: false,
        timestamps: { creation: Tue Jun 24 2014 11:37:08 GMT+0200 (CEST) },
        level: 'info'
      },
      {
        parent: 53a946c41f6d7a5d729e047f,
        title: 'My notification',
        author: 53a946c41f6d7a5d729e0477,
        action: 'create',
        object: 'form',
        link: 'http://localhost:8888',
        _id: 53a946c41f6d7a5d729e0480,
        __v: 0,
        target: [ {objectType: 'user', id: 53a946c41f6d7a5d729e0478} ],
        read: false,
        timestamps: { creation: Tue Jun 24 2014 11:37:08 GMT+0200 (CEST) },
        level: 'info'
      },
      {
        parent: 53a946c41f6d7a5d729e047f,
        title: 'My notification',
        author: 53a946c41f6d7a5d729e0477,
        action: 'create',
        object: 'form',
        link: 'http://localhost:8888',
        _id: 53a946c41f6d7a5d729e0481,
        __v: 0,
        target: [ {objectType: 'user', id: 53a946c41f6d7a5d729e0479} ],
        read: false,
        timestamps: { creation: Tue Jun 24 2014 11:37:08 GMT+0200 (CEST) },
        level: 'info'
      }
    ]

## GET /api/notifications

List all the notifications where the target is the current user.

**Request Headers:**

- Accept: application/json

**Request Attributes:**

- read=(true, false, all): Include notifications which have been read or not or all.

**Response Headers:**

- Content-Length: Document size

**Status Codes:**

- 200 OK.

**Request:**

    GET /api/notifications?read=all
    Accept: application/json
    Host: localhost:8080

**Response:**

    HTTP/1.1 200 OK
    [
      {
        "_id": "9292938883883993929",
        "author": "937887399292838838",
        "read": "true",
        "title": "New form",
        "action": "created",
        "object": "form",
        "link": "http://localhost:3000/form/123456789",
        "level": "transient",
        "target": [{objectType: "user", id: "userB"}, {objectType: "user", id: "userC"}, {objectType: "user", id: "userD"}]
      },
      {
        "_id": "9292938883883993930",
        "author": "937887399292838838",
        "read": "false",
        "title": "New result",
        "action": "filled",
        "object": "form",
        "link": "http://localhost:3000/form/123456789",
        "level": "transient",
        "target": [{objectType: "user", id: "userA"}]
      }
    ]

## GET /api/notifications/{id}

Get a single notification from its ID even if it has been read.

**Request Headers:**

- Accept: application/json

**Parameters:**

- id: The notification ID.

**Response Headers:**

- Content-Length: Document size

**Status Codes:**

- 200 OK.

**Request:**

    GET /api/notifications/9292938883883993929
    Accept: application/json
    Host: localhost:8080

**Response:**

    HTTP/1.1 200 OK
    {
      "_id": "9292938883883993929",
      "author": "937887399292838838",
      "read": "true",
      "title": "New result",
      "action": "filled",
      "object": "form",
      "link": "http://localhost:3000/form/123456789",
      "level": "transient",
      "target": [{objectType: "user", id: "userA"}]
    }

## PUT /api/notifications

Mark one or more notifications as read. When used with the last_read_at parameter, mark all the notifications before the date as read, keep newer ones as unread.

**Request Headers:**

- Accept: application/json

**Request Attributes:**

- last_read_at: Timestamp of the last read notification. If not set, default is Date.now().
- ids[]: The ids of the notifications to set as read.

**Response Headers:**

- Content-Length: Document size

**Status Codes:**

- 205 Reset Content. The notification(s) has been marked as read.
- 403 Forbidden. Current user is not authorized to set the notification as read (not creator).

**Request:**

    PUT /api/notifications
    Accept: application/json
    Host: localhost:8080

**Response:**

    HTTP/1.1 205 Reset Content