publish: update webhook docs, add JSON formatting to cookbook

generated from commit 60df2a85c7

cookbook.html

@@ -260,6 +260,9 @@
                   <li>
                     <a href="#floating-point-data" class="toc-h2 toc-link" data-title="Floating Point Data">Floating Point Data</a>
                   </li>
+                  <li>
+                    <a href="#sending-and-storing-json" class="toc-h2 toc-link" data-title="Sending and Storing JSON">Sending and Storing JSON</a>
+                  </li>
               </ul>
           </li>
 
@@ -278,7 +281,7 @@
 
       <div class="content">
         <h1 id='adafruit-io-api-cookbook'>Adafruit IO API Cookbook</h1>
-<p>This page contains a number of recipes related to Adafruit IO which have been found useful in the past. You can add and contribute to this file by filing an <code>issue</code> on the GitHub repository, or by editing this file and submitting a pull request. </p>
+<p>This page contains a number of recipes related to Adafruit IO which have been found useful in the past. You can add and contribute to this file by filing an <code>issue</code> on the GitHub repository, or by editing this file and submitting a pull request.</p>
 <h2 id='sending-and-sending-image-data-with-adafruit-io'>Sending and Sending image data with Adafruit IO</h2>
 <p>Using an <em>Image Block</em>, you can automatically display a Base64 image data string on your dashboard by sending a Base64 image data string to an Adafruit IO feed.</p>
 
@@ -308,7 +311,55 @@ or the <a href="https://io.adafruit.com/blog/tips/2016/07/14/naming-feeds">IO De
 <h3 id='notify-webhooks'>Notify Webhooks</h3>
 <p>If you only want to be notified that an event has happened, rather than have to handle all the data from an event--for example, if a service like GitHub is trying to send 7KB of JSON to your ESP8266--add <code>/notify</code> to the end of your Adafruit IO webhook URL. When data arrives, your feed will receive the message &quot;ping&quot;.</p>
 <h2 id='floating-point-data'>Floating Point Data</h2>
-<p>If you&#39;re sending <code>3.1415</code> and only want to send <code>3.14</code> - reduce the value to the desired amount of precision in your code. You can round (up or down) or truncate this value to get it in the format you want Adafruit IO to display. </p>
+<p>If you&#39;re sending <code>3.1415</code> and only want to send <code>3.14</code> - reduce the value to the desired amount of precision in your code. You can round (up or down) or truncate this value to get it in the format you want Adafruit IO to display.</p>
+<h2 id='sending-and-storing-json'>Sending and Storing JSON</h2><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
+  </span><span class="s2">"value"</span><span class="p">:</span><span class="w"> </span><span class="mf">22.587</span><span class="p">,</span><span class="w">
+  </span><span class="s2">"lat"</span><span class="p">:</span><span class="w"> </span><span class="mf">38.1123</span><span class="p">,</span><span class="w">
+  </span><span class="s2">"lon"</span><span class="p">:</span><span class="w"> </span><span class="mf">-91.2325</span><span class="p">,</span><span class="w">
+  </span><span class="s2">"ele"</span><span class="p">:</span><span class="w"> </span><span class="mi">112</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre>
+<p>Because Adafruit IO supports additional features beyond a basic MQTT brokering service, such as location tagging for data points, the service supports data in the JSON format described in the <a href="/#create-data">HTTP create data API description</a>.</p>
+
+<p>This lets us store the individual value, <code>22.587</code>, and data about the value: its latitude, longitude, and elevation. Data about the data is &quot;metadata&quot;!</p>
+
+<p>But what happens when the value you want to send is itself JSON? Good news! There are a few solutions available to you in that situation.</p>
+<h3 id='double-encoded-json-strings'>Double encoded JSON strings</h3><pre class="highlight javascript tab-javascript"><code><span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">({</span>
+  <span class="s2">"value"</span><span class="p">:</span> <span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">({</span><span class="s2">"sensor-1"</span><span class="p">:</span><span class="mf">22.587</span><span class="p">,</span><span class="s2">"sensor-2"</span><span class="p">:</span><span class="mf">13.182</span><span class="p">})</span>
+<span class="p">})</span>
+</code></pre>
+<p><strong>The safest way to can send JSON data as a value</strong> is to &quot;double encode&quot; it before sending, in which case IO will treat it as a raw string. If you&#39;re using something like javascript&#39;s <code>JSON.stringify</code> function or Ruby&#39;s <code>JSON.generate</code>, double encoding means passing the result of <code>JSON.stringify</code> through <code>JSON.stringify</code> a second time</p>
+
+<p>The double encoded JSON string can be sent directly through Adafruit IO without interference from our processing system, because the processing system will not interpret it as JSON. In your receiving code, because the value passed through includes surrounding double quotes, you have to call your parse function twice to restore the JSON object.</p>
+
+<p><code>JSON.parse(JSON.parse(input))</code></p>
+<h3 id='io-formatted-json'>IO formatted JSON</h3><pre class="highlight json tab-json"><code><span class="p">{</span><span class="w">
+  </span><span class="s2">"value"</span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="s2">"sensor-1"</span><span class="p">:</span><span class="mf">22.587</span><span class="p">,</span><span class="s2">"sensor-2"</span><span class="p">:</span><span class="mf">13.182</span><span class="p">},</span><span class="w">
+  </span><span class="s2">"lat"</span><span class="p">:</span><span class="w"> </span><span class="mf">38.1123</span><span class="p">,</span><span class="w">
+  </span><span class="s2">"lon"</span><span class="p">:</span><span class="w"> </span><span class="mf">-91.2325</span><span class="p">,</span><span class="w">
+  </span><span class="s2">"ele"</span><span class="p">:</span><span class="w"> </span><span class="mi">112</span><span class="w">
+</span><span class="p">}</span><span class="w">
+</span></code></pre>
+<p>The simplest way to send JSON data to Adafruit IO is include it directly in the datum formatted record you send to IO. For example, if instead of 22.587, I wanted to send something like, {&quot;sensor-1&quot;:22.587,&quot;sensor-2&quot;:13.182}, the &quot;wrapped&quot; version would look like the value on the right.</p>
+
+<p>It&#39;s worth noting that because Adafruit IO parses the entire JSON object that you send it, any valid JSON will be parsed and when it is stored in our system and forwarded to any subscribers, it will be regenerated. The significance of that is that if you publish JSON data with whitespace, it will be stored and republished without whitespace, because our generator produces the most compact JSON format possible.</p>
+<h3 id='non-io-formatted-json'>Non-IO formatted JSON</h3><pre class="highlight plaintext"><code>curl -H "Content-Type: application/json" \
+    -H "X-AIO-Key: toomanysecrets" \
+    --data '{"sensor-1":22.587,"sensor-2":13.182}' \
+    https://io.adafruit.com/api/v2/username/feeds/feed-key/data
+
+</code></pre>
+<p>Another way you can send raw JSON data is to just send it. If Adafruit IO doesn&#39;t find a &quot;value&quot; key in the JSON object you send, it will treat the whole blob as plain text and store and forward the data. That means with our example JSON object, sending the string <code>{&quot;sensor-1&quot;:22.587,&quot;sensor-2&quot;:13.182}</code> will result in <code>{&quot;sensor-1&quot;:22.587,&quot;sensor-2&quot;:13.182}</code> being stored in IO and sent to MQTT subscribers.</p>
+
+<p><strong>NOTE:</strong> This solution is the riskiest, because if your JSON blob includes the key named <code>value</code>, then IO will interpret <em>that</em> as the value you want to store and ignore all the other keys.</p>
+<h3 id='that-39-s-not-json-at-all'>That&#39;s not JSON at all!</h3><pre class="highlight javascript tab-javascript"><code><span class="nx">btoa</span><span class="p">(</span><span class="nx">JSON</span><span class="p">.</span><span class="nx">stringify</span><span class="p">({</span> <span class="s2">"something"</span><span class="p">:</span> <span class="s2">"here"</span> <span class="p">}))</span>
+<span class="c1">// "eyJzb21ldGhpbmciOiJoZXJlIn0="</span>
+<span class="nx">atob</span><span class="p">(</span><span class="s2">"eyJzb21ldGhpbmciOiJoZXJlIn0="</span><span class="p">)</span>
+<span class="c1">// {"something":"here"}</span>
+</code></pre>
+<p>If you want to be absolutely sure that Adafruit IO will not interfere with the data you&#39;re sending, encode it as a <a href="https://en.wikipedia.org/wiki/Base64">Base64</a> string first.</p>
+
+<p>This solution is also ideal if you want to store or send binary data with Adafruit IO. You won&#39;t get to see any pretty charts, but your data will remain exactly the way you left it.</p>
 
       </div>