docs: changed epoch to optional; added documentation to note iso8601 option; added note to explain JSON events as either single JSON object or array

Author: davidsulpy

apiary.apib

@@ -95,15 +95,17 @@ This is the main endpoint for shipping data to Initial State's Events Api. The d
 |`X-IS-BucketKey`|This is a user generated key and can be any string exluding characters `:`, `"`, `'`. See *Bucket Creation* endpoint|
 
 **Event JSON Entity**
-> Note: JSON events can be sent as either a single object as the root of the http body, or inside an array of events with the root of the HTTP body being an array `[]`
+> **Note**: JSON events can be sent as either a single object as the root of the http body, or inside an array of events with the root of the HTTP body being an array `[]`
 
 |name|required|type|max length|notes|
 |----|----|-----|---|---|
 |key |*true*|`string`|100 characters|stream key name|
 |value |*true*|`string`, `bool`, or `number`|2000 characters|stream value|
-|epoch |*false*|`number`||epoch|
+|epoch |*false*|`number`||epoch is in seconds with fractional seconds to left of decimal.|
 |iso8601|*false*|`string`||ISO-8601 Timestamp|
 
+> **Timestamping**: If the client doesn't provide a timestamp, a server timestamp will be automatically provided. If a client provides a valid "epoch" value, the "epoch" will be used instead. If the "iso8601" value is supplied it will be used instead. It's important to note, that if both a valid "epoch" and "iso8601" are supplied, the "epoch" will be used as the source of truth.
+
 + Request
     + Headers