Add WIP docs for the client-server bit of push.

drafts/push_csapi.rst

@@ -0,0 +1,52 @@
+Push Notifications
+==================
+
+Pushers
+-------
+To receive any notification pokes at all, it is necessary to configure a
+'pusher' on the Home Server that you wish to receive notifications from. There
+is a single API endpoint for this::
+
+Fetching a user account displayname::
+
+	POST $PREFIX/pushers/set
+
+This takes a JSON object with the following keys:
+
+pushkey
+  This is a unique identifier for this pusher. The value you should use for this
+  is the routing or destination address information for the notification, for
+  example, the APNS token for APNS or the Registration ID for GCM. If your
+  notification client has no such concept, use any unique identifier.
+kind
+  The kind of pusher to configure. 'http' makes a pusher that sends HTTP pokes.
+  null deletes the pusher.
+instance_handle
+  This is an identifier for the device which owns the pusher. It may be up to 32
+  characters long. It must be unique among all the pushers for a given user
+  (therefore the device ID may not be used). It is advised that when an app's
+  data is copied or restored to a different device, this ID remain the same (ie.
+  be shared by multiple pushers for multiple devices). Client apps should be
+  aware that this situation can occur and be able to rectify it (eg. by
+  offerring to reset the instance_hanlde, optionally duplicating all push rules
+  to new instance handle).
+app_id
+  appId is a reverse-DNS style identifier for the application. It is recommended
+  that this end with the platform, such that different platform versions get
+  different app identifiers. Max length, 64 chars.
+app_display_name
+  A string that will allow the user to identify what application owns this
+  pusher.
+device_display_name
+  A string that will allow the user to identify what device owns this pusher.
+lang
+  The preferred language for receiving notifications (eg, 'en' or 'en-US')
+data
+  A dictionary of information for the pusher implementation itself. For HTTP
+  pushers, this must contain a 'url' key which is a string of the URL that
+  should be used to send notifications.
+
+If the pusher was created successfully, an empty JSON dictionary is returned.
+
+
+