Clarify bridge documentation

[jrconlin]

There is clear confusion regarding how to use the bridge HTTP interface.

Address these concerns.

2:20 PM <kitcambridge> i've come to the conclusion i don't understand anything on http://autopush.readthedocs.io/en/latest/http.html#push-service-bridge-http-interface
2:22 PM <kitcambridge> specifically, i'm confused what "The bridge specific public exchange token" and "The bridge specific private identifier token" are, what token is in `POST /v1/{type}/{token}/registration`, and how that's different from {"token": "1ab2c3"}
2:24 PM <kitcambridge> and what's "Authorization: WebPush 0123abcdef", isn't that vapid? do we use vapid for the http bridge, too?
2:28 PM <•jrconlin> kitcambridge: yeah, the problem is that "token" is very generic.
2:30 PM <•jrconlin> In the URL "token" (as defined by third party systems that use it and call it "token") is the sender identifier. For GCM/FCM it's SenderID, for APNS it's irrelevant.
2:30 PM <•jrconlin> For the body "token" is (as defined by the same third party systems that use and call it "token" because they hate me) is the client ID token. For both of these, it's a long string identifier. 
2:31 PM — kitcambridge is so confused
2:32 PM <•jrconlin> I feel your pain.
2:32 PM <•jrconlin> O
2:32 PM <kitcambridge> so the senderID is a token, the client ID is a token, but the client ID is not the uaid, and there's an auth_token that's a bearer token
2:32 PM <•jrconlin> I will happily go and revamp the docs to be less confusing, provided I can figure out how to best specify exactly that.
2:33 PM <•jrconlin> pretty much.
2:33 PM <•jrconlin> And I can't use "senderID" because that's limited to a single bridge system.
2:33 PM <kitcambridge> ok
2:35 PM <kitcambridge> what's the apns version of senderID?
2:35 PM <•jrconlin> If it's any help, I have to verify that the "auth_token" mentioned is the secret handed back in the registration.
2:35 PM <•jrconlin> for APNS, the senderID is irrelevant. use any value, like "aaaa" if you want.
2:36 PM <kitcambridge> oh, so the auth_token isn't a vapid thing?
2:36 PM <•jrconlin> no, since it predates vapid.
2:36 PM <kitcambridge> what does it do?
2:37 PM <•jrconlin> bearer token for auth. 
2:37 PM <kitcambridge> looks like it's just the secret that gets passed back on registration?
2:37 PM <•jrconlin> That is what I'm looking to confirm.
2:37 PM <benbangert> kitcambridge: its to reduce the attack vector of griefers guessing UUID's
2:38 PM <benbangert> we won't honor requests to add/drop sub's if the auth token doesn't match the UAID
2:39 PM <kitcambridge> ah cool
2:40 PM <•jrconlin> confirmed, it's a simple bearer token provided by the registration call. Will update the docs to be clearer about that.
2:40 PM <•jrconlin> I may also change the type name from WebPush to "Bearer" since that's resolved now.
2:40 PM <•jrconlin> (Code actually ignores that bit)
2:41 PM <kitcambridge> ok, so...
2:41 PM <kitcambridge> let's say i want to register for gcm
2:41 PM <•jrconlin> ok.
2:42 PM <kitcambridge> i do POST /v1/gcm/mySenderID/registration with no Authorization header and { token: "myClientIDToken" } in the body
2:42 PM <•jrconlin> kitcambridge: correct.
2:43 PM <kitcambridge> that stores mySenderID and myClientID in dynamo, and creates an endpoint for me, too
2:43 PM <kitcambridge> and i get back a uaid, secret, channelID, endpoint
2:43 PM <•jrconlin> correct
2:43 PM <kitcambridge> awesome
2:43 PM <kitcambridge> now, i want to register another channel
2:44 PM <•jrconlin> ok.
2:44 PM <kitcambridge> so, i do POST /v1/gcm/mySenderID/registration/uaid/subscription
2:44 PM <•jrconlin> You PUT, but yes, to that URL.
2:44 PM <kitcambridge> oh, ok
2:45 PM <•jrconlin> Sorry, my fault, 
2:45 PM <kitcambridge> so i PUT to that
2:45 PM <kitcambridge> nothing in the body
2:45 PM <•jrconlin> You POST. Doc wasn't updated.
2:45 PM <•jrconlin> ARGH! 
2:45 PM <kitcambridge> oh, no worries. ok, so I POST, with nothing in the body, and a `Authorization: Bearer {secret}` header
2:45 PM <•jrconlin> it's put. (really need to fix that.)
2:47 PM <kitcambridge> ok, and to update, if the senderID or the myClientIDToken changes...
2:47 PM <kitcambridge> i do PUT /v1/gcm/senderID/registration/{uaid}
2:47 PM <kitcambridge> also with `Authorization: Bearer {secret}`
2:47 PM <•jrconlin> argh2: it's POST, Put is used to change the third party id used to identify the recipient.
2:47 PM <kitcambridge> and with { token: "myNewClientIDToken" } in the body
2:47 PM <•jrconlin> Correct.
2:49 PM <kitcambridge> ok, cool, thanks :-)
2:49 PM <kitcambridge> now, if i'm apns, then there's no senderID
2:50 PM <kitcambridge> so the url prefix is going to be something like /v1/apns/aaaa/registration
2:50 PM <•jrconlin> yep.
2:51 PM <•jrconlin> We need that "aaaa" bit just because it's expected by the server, but the code ignores it completely.
2:51 PM <•jrconlin> You can use any, rendering value, like "a" or "0" if you like.
2:52 PM <•jrconlin> And the code cleanup refactor just blew chunks all over my git repo. Yay!
2:53 PM <kitcambridge> gotcha
2:55 PM — kitcambridge saves this scrollback for future reference
2:56 PM <kitcambridge> walking through that was really helpful, jrconlin. thanks!
2:56 PM <•jrconlin> heh, yeah, well, now i get to translate that into the docs, too. 
2:56 PM <•jrconlin> And yeah, clearing up the syntax helps a lot.
2:57 PM <kitcambridge> it was useful to see the flow