Merge pull request #136 from TelemetryDeck/docs/update-rest-api

Update the V2 Integration Page

Author: kkostov

.styles/config/vocabularies/Base/accept.txt

@@ -48,6 +48,7 @@ anonymization
 glowy
 pseudonymization
 namespaced
+namespace
 Bool
 Vue
 (npm|NPM)
@@ -71,4 +72,4 @@ SDKs
 Walkthrough
 multiple
 unpublished
-UUID
+UUID

ingest/v2.md

@@ -1,22 +1,24 @@
 ---
 title: Ingest API v2
 tags: overview
-description: Use the TelemetryDeck Ingest API to send signals to TelemetryDeck
-lead: Use the TelemetryDeck Ingest API to send signals to TelemetryDeck
+description: Use the TelemetryDeck Ingest API to send events to TelemetryDeck
+lead: Use the TelemetryDeck Ingest API to send events to TelemetryDeck
 order: 0
 headerImage: /img/ingestv2.jpg
 ---
 
-Usually you'll send signals to TelemetryDeck using one of our SDKs. However, if you're working with a language or framework that we don't have an SDK for, you can send signals directly to our Ingest API.
+Usually you'll send events to TelemetryDeck using one of our SDKs. However, if you're working with a language or framework that we don't have an SDK for, you can send events directly to our Ingest API.
 
 ## Ingest Endpoint
 
-Please send your signals as POST request to our ingestion server at `https://nom.telemetrydeck.com/v2/`, with the headers `Content-Type: application/json` and `charset=utf-8`.
+Please send your events as a POST request to our ingestion server at `https://nom.telemetrydeck.com/v2/namespace/{namespace}/`, with the headers `Content-Type: application/json` and `charset=utf-8`.
+
+Replace `{namespace}` with your organization's TelemetryDeck namespace. You can find your namespace in the [TelemetryDeck Dashboard](https://dashboard.telemetrydeck.com/).
 
 Here's an example in cURL:
 
 ```bash
-curl -X "POST" "https://nom.telemetrydeck.com/v2/" \
+curl -X "POST" "https://nom.telemetrydeck.com/v2/namespace/your-namespace/" \
      -H 'Content-Type: application/json; charset=utf-8' \
      -d $'[
         {
@@ -29,20 +31,21 @@ curl -X "POST" "https://nom.telemetrydeck.com/v2/" \
 
 ## Body Structure
 
-The post body should be an **array of JSON objects**, because you can send multiple signals at once. Each signal object **must** have these properties:
+The post body should be an **array of JSON objects**, because you can send multiple events at once. Each signal object **must** have these properties:
 
 | Property     | Type   | Description                                                                                                                                                                                                                               |
 | ------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `appID`      | string | Your app's ID                                                                                                                                                                                                                             |
 | `clientUser` | string | A hash of the user's ID. This should always be the same for the same user.                                                                                                                                                                |
-| `type`       | string | The type of signal. While it is not enforced, we recommend structuring your signal names in name spaces separated by dots, with the signal type beginning with a lower case letter and any namespaced beginning with an uppercase letter. |
+| `type`       | string | The type of signal. While it is not enforced, we recommend structuring your signal names in scopes separated by dots, with the signal type beginning with a lowercase letter and any scope beginning with an uppercase letter. |
 
 The following properties are optional:
 
 | Property     | Type   | Description                                                                                 |
 | ------------ | ------ | ------------------------------------------------------------------------------------------- |
 | `sessionID`  | string | The user's session ID. This should be the same value for the same session/user combination. |
 | `isTestMode` | Bool   | If `true`, the signal will be excluded from production queries. Defaults to `false`.        |
+| `floatValue` | number | A numeric measurement. Use for any numeric operations, such as building averages or sums.   |
 | `payload`    | object | A JSON object with additional data.                                                         |
 
 ## Payload
@@ -56,46 +59,33 @@ The `payload` object can contain data you want to send to TelemetryDeck. It must
   "type": "Curl.Development.apiCall",
   "sessionID": "mySessionID",
   "isTestMode": false,
+  "floatValue": 3.14159,
   "payload": {
     "TelemetryDeck.RunContext.locale": "en_US",
-    "TelemetryDeck.Device.architecture": "x86_64",
-    "floatValue": 3.14159
+    "TelemetryDeck.Device.architecture": "x86_64"
   }
 }
 ```
 
-Payload keys should be in the format `Namespace.OptionalSubNamespace.key`, with the name spaces capitalized and the key starting with a lowercase letter. This is not enforced but helps you organize your payload dimensions and fit in better with TelemetryDeck's internal payload keys.
+Payload keys should be in the format `Scope.OptionalSubScope.key`, with the scopes capitalized and the key starting with a lowercase letter. This is not enforced but helps you organize your payload dimensions and fit in better with TelemetryDeck's internal payload keys.
 
 The value can be any primitive JSON value, but we'll convert it to a string before storing it, except for a number of special cases that are stored as their original type.
 
 The payload should not contain nested objects. The behavior of arrays of strings is left undefined and should be avoided (except if you have a deep knowledge of [multi-value dimensions in Apache Druid](https://druid.apache.org/docs/latest/querying/multi-value-dimensions/)).
 
-## Special Payload Values
-
-The following payload values are not converted to strings, but need to be sent as their respective types:
+## Numeric Values
 
-| Property     | Type  | Description                                                                                             |
-| ------------ | ----- | ------------------------------------------------------------------------------------------------------- |
-| `floatValue` | Float | A floating point number. Use for any numeric operations, such as building averages or adding up values. |
+The `floatValue` field is a top-level property on the signal object (see the optional properties table above). It is not part of the `payload` object. Use it for any numeric operations such as building averages or adding up values.
 
 {% noteinfo "More special values" %}
-More special values are coming soon for internal use.
+More special top-level fields are coming soon for internal use.
 
-- The ones being defined in [this PR](https://github.com/TelemetryDeck/docs/pull/85) need to be implemented server side first.
+- The ones being defined in [this PR](https://github.com/TelemetryDeck/docs/pull/85) need to be implemented server-side first.
 - We're preparing a number of special values specifically for metrics and crashes, but these need to be defined first.
   {% endnoteinfo %}
 
-## Forbidden Payload Values
-
-You are not allowed to send the following keys in the payload:
+## Reserved Payload Keys
 
-- `count`
-- `type`
-- `appID`
-- `clientUser`
-- `__time`
-- `payload`
-- `platform`
-- `receivedAt`
+Some payload keys are reserved for internal use by TelemetryDeck. See the [complete list of reserved parameters](/docs/ingest/default-parameters/#reserved-parameters) which you're not allowed to include in the payload.
 
-These keys are reserved for internal use. If you use them, we'll rename them on the server for you by prepending an underscore. For example, if you send `count`, we'll store it as `_count`.
+In general, avoid using parameter names that begin with the `TelemetryDeck.` scope, as this is reserved for parameters set by TelemetryDeck SDKs and the ingestion server.