Channels

Basically the idea being channels is the same as TV channels where one broadcast a message and others can listen to it.

The idea is that people can listen to channels even if they don’t exists.

The service configuration as well as the permission backend define a list of users that can publish on given channels.

Register to a channel

PUT /channels/(channel_id)/registration
synopsis:Subscribe the user to the channel

Requires authentication

Example Request

$ http PUT http://localhost:9999/v0/channels/formbuilder-collections-update/registration Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v
PUT /v0/channels/formbuilder-collections-update/registration HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 202 Accepted
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Date: Thu, 18 Jun 2015 17:02:23 GMT
Server: waitress


{"code": 202, "message": "Accepted"}

Unsubscribing from a channel

DELETE /channels/(channel_id)/registration
synopsis:Unsubscribe the user from the channel

Requires authentication

Example Request

$ http delete http://localhost:9999/v0/channels/formbuilder-collections-write/registration Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v
DELETE /v0/channels/formbuilder-collections-update/registration HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Portier dccd8ac07f3e45c9907da638e994ff98
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 202 Accepted
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Date: Thu, 18 Jun 2015 17:02:23 GMT
Server: waitress


{"code": 202, "message": "Accepted"}

Getting channels informations

GET /channels/(channel_id)
Synopsis:Retrieve channel informations

Example Request

$ http get http://localhost:9999/v0/channels/formbuilder-collection-write Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v
GET /v0/channels/formbuilder-collection-write HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Basic Ym9iOg==
Connection: keep-alive
Host: localhost:9999
User-Agent: HTTPie/0.9.2

Example Response

HTTP/1.1 200 OK
Access-Control-Expose-Headers: Backoff, Retry-After, Alert, Last-Modified, ETag
Content-Length: 211
Content-Type: application/json; charset=UTF-8
Date: Thu, 18 Jun 2015 17:29:59 GMT
Etag: "1434648599199"
Last-Modified: Thu, 18 Jun 2015 17:29:59 GMT
Server: waitress

{
    "data": {
        "id": "formbuilder-collection-write",
        "registrations": 1,
        "push": 0
    }
}
  • registration contains the number of users that subscribed to the channel.
  • push contains the number of push that were sent to the channel.

Broadcasting a push notification

For the first version, only users configured in the service configuration can broadcast notifications.

However in the future we aim at adding a permissions management feature to the channel.

POST /channels/(channel_id)
synopsis:Push a notification

Requires authentication

Example Request

$ http post http://localhost:9999/v0/channels/formbuilder-collections-write Authorization:"Portier dccd8ac07f3e45c9907da638e994ff98" -v
POST /v0/channels/formbuilder-collections-update HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Basic Ym9iOg==
Connection: keep-alive
Content-Length: 25
Content-Type: application/json
Host: localhost:9999
User-Agent: HTTPie/0.9.2

{
  "data": {
      "last_modified": 1434647996969
  }
}

Example Response

HTTP/1.1 202 Accepted
Access-Control-Expose-Headers: Backoff, Retry-After, Alert
Date: Thu, 18 Jun 2015 17:02:23 GMT
Server: waitress


{"code": 202, "message": "Accepted"}

The data payload will be encrypted for each subscriptions and sent authenticated through the endpoint.