|
|
| Line 117: |
Line 117: |
| * '''POST Office''': Responsible for forwarding all notifications sent by web apps to the Message Broker. | | * '''POST Office''': Responsible for forwarding all notifications sent by web apps to the Message Broker. |
|
| |
|
| * '''Agent''': Responsible for all REST-API calls, this handles the creation of exchanges and queues within the Message Broker on behalf of clients. | | * '''Client Agent''': Handles the creation of exchanges and queues within the Message Broker on behalf of clients. The Client uses the Client Agent as a means to register itself and create and remove subscriptions. |
|
| |
|
| * '''Subscription''': Represents the relationship between a web app and a user who wishes to receive notifications from said web app. A subscription consists of the "link" that allows the web app to send notifications to the user. | | * '''Subscription''': Represents the relationship between a web app and a user who wishes to receive notifications from said web app. A subscription consists of the "link" that allows the web app to send notifications to the user. |
| Line 127: |
Line 127: |
| * '''Client Queue''': Entity within the message broker where all messages destined for a particular client of a user are sent (one queue per client). | | * '''Client Queue''': Entity within the message broker where all messages destined for a particular client of a user are sent (one queue per client). |
|
| |
|
| == Server API == | | == Server APIs == |
|
| |
|
| The Server API consists of a standard REST API, using HTTP GET, POST, PUT, and DELETE commands to retrieve and manipulate resources. The following table gives a summary of the API supported by the Agent:
| | [[Services/Notifications/Specification/POSTOffice | POST Office]] |
| | | [[Services/Notifications/Specification/ClientAgent | Client Agent]] |
| {| class="wikitable"
| |
| |-
| |
| ! Path
| |
| ! Description
| |
| |-
| |
| | /notifications
| |
| | Methods: '''POST'''
| |
| Used by web apps to send notifications. The body of the HTTP request should contain a JSON string of the following form:
| |
| <pre>
| |
| {"routing_key": "routing key",
| |
| "type": "the type of notification",
| |
| "timestamp": "UNIX timestamp",
| |
| "payload": "notification message"}
| |
| </pre>
| |
| | |
| |-
| |
| | /users/'''name'''/subscriptions
| |
| | Methods: '''GET''', '''POST''' | |
| Requires authentication.
| |
| GETting this retrieves all subscriptions for the user with the specified name. Appending a query string at the end of the URL (e.g. ''?app_host=mail.google.com&app_name=GMail'') will filter the results by the fields specified. This is useful for determining if a particular subscription exists for a given application name/host pair. The list is returned as a JSON string of the form:
| |
| <pre>
| |
| [{"routing_key": "routing_key", | |
| "app_name": "Name of app",
| |
| "app_host": "Domain of app",
| |
| "reg_date": "Creation date"},
| |
| ...
| |
| ]
| |
| </pre>
| |
| Each item in the JSON array corresponds to a subscription for the specified user.
| |
| | |
| You can create a new subscription by POSTing to this resource with a HTTP body of the following form:
| |
| <pre>
| |
| {"app_name": "Application name",
| |
| "app_host": "Domain of web app"}
| |
| </pre>
| |
| If the application name and host field values are unique as a pair, the subscription is created and the following JSON string is returned:
| |
| <pre>
| |
| {"routing_key": "the routing key created"}
| |
| </pre>
| |
| | |
| |-
| |
| | /users/'''name'''/subscriptions/'''routing_key'''
| |
| | Methods: '''GET''', '''DELETE''' | |
| Requires authentication.
| |
| GETting this resource will return information about the subscription with the specified routing key. The returned information is of the following form:
| |
| <pre>
| |
| {"app_name": "Name of app",
| |
| "app_host": "Domain of app",
| |
| "reg_date": "Creation date"}
| |
| </pre>
| |
| If you are DELETEing this resource it will remove the subscription and send a notification to all of the user's other clients, telling them the subscription is no longer valid.
| |
| | |
| |-
| |
| | /users/'''name'''
| |
| | Methods: '''PUT'''
| |
| ''Will eventually require a more secure method of creation, e.g. CAPTCHA''
| |
| | |
| To PUT a user (i.e. create new user account) you'll need an HTTP body looking like the following:
| |
| <pre>
| |
| {"password": "user's account password"}
| |
| </pre>
| |
| |}
| |
|
| |
|
| == Security Considerations == | | == Security Considerations == |