apiary.apib

FORMAT: 1A
HOST: http://notifications-host

# Resonator microservice API

## Introduction

Notifications is a microservice that allows to send email, sms & push notifications easily.

Source code is available [here](https://github.com/thegameofcode/resonator).

# Group Identity

## /api/identity

+ Attributes(identity Base)

### Get requester's identity data [GET]

Retrieves the Identity data associated to the requester

+ Request

    + Headers

            x-user-id: 01f0000000000000003f0001


+ Response 200 (application/json; charset=utf-8)

    + Body

            {
                "id": "01f0000000000000003f0001",
                "channels": [
                    "buddies",
                    "friends"
                ],
                "devices": {
                    "email": [
                        "john@doe.com"
                    ],
                    "sms": [
                        "+15005550011"
                    ],
                    "phone": [
                        "111222333",
                        "333222111"
                    ],
                    "apn": [],
                    "gcm": [
                        "654C4DB3-3F68-4969-8ED2-80EA16B46EB0"
                    ]
                }
            }


+ Response 401 (application/json; charset=utf-8)

    + Body

            {
                "code": "UnauthorizedError",
                "message": "Missing authorization header"
            }


### Create a new Identity object [POST]

Creates a new Identity object with the provided data, if any

+ Request

    + Body

            {
                "devices": {
                    "sms": [],
                    "email": ["john@appleseed.com"],
                    "phone": [],
                    "apn": [],
                    "gcm": []
                },
                "channels": []
            }

+ Response 201 (application/json; charset=utf-8)

    + Body

            {
                "id": "55af67b553f14ff72a0f5e19"
            }

+ Response 500 (application/json; charset=utf-8)

    + Body

            {
                "code": "InternalError",
                "message": "Could not create requested Identity object"
            }

### Modify the Identity data associated to the requester [PUT]

Replaces the data of the Identity object associated to the requester with the provided contents

+ Request

    + Headers

            x-user-id: 01f0000000000000003f0001

    + Body

            {
                "devices": {
                "email": ["changed@doe.com"]
                },
                "channels": []
            }

+ Response 204

## /api/identity/{id}

### Retrieve the Identity data associated to an Identity identifier [GET]

+ Parameters
    + id (required, string, `01f0000000000000003f0002`)

        The ID of the desired Identity object


+ Request

    + Headers

            x-user-id: 01f0000000000000003f0001

+ Response 200 (application/json; charset=utf-8)

    + Body

            {
               "id": "01f0000000000000003f0002",
               "channels": [
                   "friends"
               ],
               "devices": {
                   "email": [
                       "michael@hamming.com"
                   ],
                   "sms": [
                       "+15005550014"
                   ],
                   "phone": [
                       "000222444",
                       "888666222"
                   ],
                   "apn": [
                       "<0123 4567 89AB CDEF>"
                   ],
                   "gcm": [
                       "654C4DB3-3F68-4969-8ED2-40FF45A33DC1"
                   ]
               }
            }

+ Response 401 (application/json; charset=utf-8)

    + Body

            {
                "code": "UnauthorizedError",
                "message": "Identity not found"
            }



# Group Channel

## /api/channel

+ Attributes(channel Base)

### Get the requester's channel list [GET]

Retrieves the list of Channel objects associated to the requester's Identity object

+ Request

    + Headers

            x-user-id: 01f0000000000000003f0001


+ Response 200 (application/json; charset=utf-8)

    + Body

            [
                {
                    "id": "01f0000000000000006f0001",
                    "name": "buddies"
                },
                {
                    "id": "01f0000000000000006f0002",
                    "name": "friends"
                }
            ]

+ Response 401 (application/json; charset=utf-8)

    + Body

            {
                "code": "UnauthorizedError",
                "message": "Missing authorization header"
            }

### Create a new Channel object [POST]

Creates a new Channel object with the provided name in the data store

+ Request (application/json)

    + Body

            {
                "name": "some_name"
            }

+ Response 201 (application/json; charset=utf-8)

    + Body

            {
                "id": "54af67b322f14ff72a0f5e20"
            }

+ Response 500 (application/json; charset=utf-8)

    + Body

            {
                "code": "ConflictError",
                "message": "Missing 'name' property in channel object"
            }

## /api/channel/{id}

### Modify the data associated to a Channel object [PUT]

Replaces the data of the Channel object identified by the provided channel Id.

+ Parameters
    + id (required, string, `01f0000000000000006f0001`)

        The ID of the Channel object to update

+ Attributes
    + id: 01f0000000000000006f0001 (string)

+ Request (application/json)

    + Body

            {
                "name": "new_name"
            }

+ Response 204

+ Response 409 (application/json; charset=utf-8)

    + Body

            {
                "code": "ConflictError",
                "message": "Missing 'name' property in channel object"
            }

### Delete a Channel object [DELETE]

Delete the Channel object identified by the provided channel Id.

+ Parameters
    + id (required, string, `01f0000000000000006f0001`) ... The ID of the Channel object to delete

+ Request

    + Headers

            Authorization: Bearer BEWkwDA0bTTw_4dSPNI8lDPWF

+ Response 204

+ Response 500 (application/json; charset=utf-8)

    + Body

            {
                "code": "InternalError",
                "message": "Could not delete provided channeld object"
            }

## /api/channel/{id}/identities

### Get a channel's identities list [GET]

Retrieves the list of Identity objects associated to the specified Channel object

+ Parameters
    + id (required, string, `01f0000000000000006f0001`) ... The ID of the Channel object to retrieve data from

+ Request

+ Response 200

    + Body

                [
                    {
                        "id": "01f0000000000000003f0002",
                        "channels": [
                            "01f0000000000000006f0002"
                        ],
                        "devices": {
                            "email": [
                                "michael@hamming.com"
                            ],
                            "sms": [
                                "444555666"
                            ],
                            "phone": [
                                "000222444",
                                "888666222"
                            ],
                            "apn": [],
                            "gcm": [
                                "654C4DB3-3F68-4969-8ED2-40FF45A33DC1"
                            ]
                        }
                    }
                ]

+ Response 500 (application/json; charset=utf-8)

    + Body

                {
                    "code": "BadRequestError",
                    "message": "Unknown provided channel identifier"
                }

## /api/channel/{channelId}/identities/{identityId}

### Remove an Identity from channel [DELETE]

Delete an Identity identifier from a Channel object

+ Parameters
    + channelId (required, string, `01f0000000000000006f0001`) ... The Channel identifier from which the Identity shall be removed
    + identityId (required, string, `01f0000000000000003f0001`) ... The Identity identifier that shall be removed from the Channel object

+ Request

+ Response 204

+ Response 500 (application/json; charset=utf-8)

    + Body

                {
                    "code": "InternalError",
                    "message": "Could not delete provided Identity object from channel 01f0000000000000006f0002"
                }


# Group SMS

## SMS [/api/notification/sms]

+ Attributes (sms Base)

### Send a sms [POST]
Send a new sms to a given phone number

#### Attributes for the json body parameter

Name | Type | Required | Description
--- | --- | --- | ---
__to__ | String | Required | Array which contains identity ids to send the message.
__from__ | String | Required | Phone Number sender.
__message__ | String | Required | Sms Text Message to be sent.

+ Request (application/json)

    + Body

            {
                "identities": [],
                "channels": ["buddies"],
                "content": {
                    "from": "+15005550010",
                    "message": "Hola holita RESONATOR"
                }
            }

+ Response 204



# Group Email

## Single target email [/api/notification/singleEmail]

+ Attributes (email Base)

### Send single target email [POST]
Send a new email to a single email address

#### Attributes for the json body parameter

Name | Type | Required | Description
--- | --- | --- | ---
__to__ | String | Required | Array which contains identity ids to send the message.
__from__ | String | Optional | Email sender.
__subject__ | String | Optional | Email subject.
__html__ | String | Required | Email Text Message to be sent.

+ Request (application/json; charset=utf-8)

    + Body

            {
              "to": "john@doe.com",
              "from": "mac@into.sh",
              "html": "Hello RESONATOR!",
              "subject": "Testing"
            }

+ Response 204


+ Response 400 (application/json; charset=utf-8)

            {
              "code": "BadRequestError",
              "message": "Missing 'to' property in parameters"
            }

+ Response 400 (application/json; charset=utf-8)

            {
              "code": "BadRequestError",
              "message": "Missing 'html' String property in request body"
            }

## Multiple target email [/api/notification/email]

+ Attributes (email Base)

### Send batch email [POST]
Send a new email to one or more Identities and/or Channels

#### Attributes for the json body parameter

Name | Type | Required | Description
--- | --- | --- | ---
__identities__ | Array | Optional | Array of target Identity object IDs to send the email to.
__channels__ | Array | Optional | Array of target Channel object IDs to send the email to.
__content__ | Object | Required | Email fields container.

#### Attributes for the CONTENT object of the request body

Name | Type | Required | Description
--- | --- | --- | ---
__from__ | String | Optional | Email sender.
__subject__ | String | Optional | Email subject.
__message__ | String | Required | Email text Message to be sent.

+ Request (application/json; charset=utf-8)

    + Body

            {
              "identities": ["01f0000000000000003f0001", "01f0000000000000003f0002", "01f0000000000000003f0003"],
              "channels": ["buddies"],
              "content": {
                "from": "noreply@email.com",
                "subject": "Testing",
                "message": "This is the body of the email"
              }
            }

+ Response 204


+ Response 400 (application/json; charset=utf-8)

            {
              "code": "BadRequestError",
              "message": "Missing 'to' property in parameters"
            }

+ Response 400 (application/json; charset=utf-8)

            {
              "code": "BadRequestError",
              "message": "Missing 'message' String property in request body 'content' object"
            }



# Group Push Notifications

## Push [/api/notification/push]

+ Attributes (push Base)

### Send a email [POST]
Send a new email to a given array of emails

#### Attributes for the json body parameter

Name | Type | Required | Description
--- | --- | --- | ---
__to__ | String | Required | Array which contains identities ids.
__message__ | String | Required | Push Text Message to be sent.
__optionals__ | String | Optional | Object containing all send options (onlyGcm || onlyApn).

+ Request (application/json; charset=utf-8)

    + Body

            {
                "identities": [
                    "01f0000000000000003f0002",
                    "01f0000000000000003f0003"
                ],
                "content": {
                    "apn": {
                        "alert": "You have a new message",
                        "payload": {
                            "someKey": "someValue"
                        }
                    }
                }
            }

+ Response 204

+ Response 400 (application/json; charset=utf-8)

            {
              "code": "BadRequestError",
              "message": "Missing 'to' property in parameters"
            }


+ Response 400 (application/json; charset=utf-8)

            {
              "code": "BadRequestError",
              "message": "Missing 'message' property in parameters"
            }



# Data Structures

## identity Base (object)
- devices: {} (devices Base, required) - object containing a set notification receivers grouped by type
- channels: [] (array, required) - list of Channel object identifiers that can listen to notifications and forward them to the corresponding identites


## devices Base (object)
- sms: ['+11231231234', '+99887766543'] (array, optional) - a list of sms receivers associated to the identity
- phone: ['111222333', '333222111'] (array, optional) - a list of phone numbers to receive notifications
- email: ['john@doe.com'] (array, optional) - a list of email addresses to receive notifications
- apn: [] (array, optional) - a list of APN identifiers for iOS devices to receive push notifications
- gcm: [] (array, optional) - a list of GCM identifies for Android devices to receive push notifications


## channel Base (object)
- name: +11231231234 (string, required) - human-friendly channel identifier
- identitiesRef: ['01f0000000000000003f0001'] (array, optional) - array with identity identifiers which belong to the channel


## sms Base (object)
- to: ['01f0000000000000003f0002', '01f0000000000000003f0003'] (array, required) - phone number to send the sms
- message: 'Hello world' (string, required) - text to send via sms
- from: +11231231234 (string, required) - phone number sender the sms


## email Base (object)
- from: email1@email.com (string, required) - Email sender.
- to: ['01f0000000000000003f0002', '01f0000000000000003f0003'] (array, required) - Array which contains identity ids to send the message.
- message: 'This is the body of the email' (string, required) - Email Text Message to be sent.


## push Base (object)
- to: ['01f0000000000000003f0002', '01f0000000000000003f0003'] (array, required) - Array which contains identities ids.
- message: 'This is the body notification data' (string, required) - Push Text Message to be sent.