api::auth route parameters have updated notes regarding types

docs/api.md

@@ -1,28 +1,47 @@
-# NOTE:
+# Preface
-
-This document makes no attempt to outline/describe how voice connections are handled by the server/client.
-That information is found elsewhere.
 
+Voice connections are not yet authored as they are far from being implemented
 
 # Auth Routes
 
+## Logging in
+
+Authenticated routes require a session key which this route provides, given a previously invited user's credentials
+
 ```
 /auth/login
 ```
 
 Parameters:
-	username
+	- id
-		set via a config the first time the app is started up
+		User id provided by the instance
-	server-generated-access-key
+	- secret
-		this is given to us the first time we join the server
+		API key provided by the instance
+
 Return:
-	Session key
+	- api-key
+		Binary string base64 encoded. This encoding is not to be undone or further authentication _will_ fail.
+	- expiration
+		Unix time stamp dictating when this key should be deleted server side. Though the server may delete the key later than this time-stamp the client can request a new token via `/auth/login` or `/auth/refresh`.
+		
+
+## Leaving an instance
+
+Parameters
+	- id
+		User id provided by the instance
+	- secret
+		API key provided by the instance
+Return:
+	On success: A simple HTTP 200 response; empty body.
+	On failure: An HTTP 400 Bad Request response; which parameter is wrong is not specified to avoid enumeration style attacks.
+
 
 # Channels
 
 ```
-/channels/list/<voice>
+/channels/list/voice
-/channels/list/<text>
+/channels/list/text
 ```
 
 Return:
@@ -40,15 +59,33 @@ Return:
 ```
 
 Parameters:
-	opt::limit
+	- from::UnixTimestamp<u64>
-		Request the last <X> hours of messages.
+		DateTime from which to pull messages. Max value on this route can be no more than 72 hours in the past. To pull further messages you will need to use the `/message/range` route.
-		By default the last 24 hours of messages is given unless otherwise specified
 		
-Behavior:
+```
-	Should really only be necessary to update channel members periodically when the client is opened up to that server exactly.
+/message/range
+```
+
+Parameters:
+	- start::UnixTimestamp<u64>
+	- end::UnixTimestamp<u64>
+
+On this route instances by default allow up to 1 week worth of range. Note of course that the closer a client gets to this maximum the longer it will take to load. Some instances may be configured to only return a certain number of messages as well so it is worthwhile to check the bounds of the messages a client receives.
+
+On success:
+	A json encoded list of `struct::Message` will be returned with a 200 Ok
+
+On paramter failure: 
+	HTTP 400 Bad request
+
+On server error: 
+	HTTP 500 Internal Server Error
 
 # Structures
 
+Below are various structures that client builds can expect to receive.
+
+```
 Member {
 	name: string
 	id: u64
@@ -72,4 +109,4 @@ Badge {
 	permissions: u64
 	color: u32
 }
-
+```