You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@usergrid.apache.org by sn...@apache.org on 2016/02/18 16:53:04 UTC
[56/89] usergrid git commit: Major Updates. See commit details.
http://git-wip-us.apache.org/repos/asf/usergrid/blob/c638c774/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/Documents/index.html
----------------------------------------------------------------------
diff --git a/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/Documents/index.html b/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/Documents/index.html
index e9f34a6..91cbf58 100644
--- a/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/Documents/index.html
+++ b/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/Documents/index.html
@@ -156,23 +156,27 @@
<a href='#usergridsdk' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h1 id='usergridsdk'>UsergridSDK</h1>
-<p><a href="https://travis-ci.org/RobertWalsh/UsergridSDK"><img src="https://travis-ci.org/RobertWalsh/UsergridSDK.svg" alt="Build Status"></a>
-<a href="http://cocoadocs.org/docsets/UsergridSDK"><img src="https://img.shields.io/cocoapods/p/UsergridSDK.svg?style=flat" alt="Platform"></a>
-<a href="https://img.shields.io/cocoapods/v/UsergridSDK.svg"><img src="https://img.shields.io/cocoapods/v/UsergridSDK.svg" alt="Cocoapods Compatible"></a>
-<a href="https://github.com/Carthage/Carthage"><img src="https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat" alt="Carthage Compatible"></a></p>
+<p><a href="http://cocoadocs.org/docsets/UsergridSDK"><img src="https://img.shields.io/cocoapods/p/UsergridSDK.svg?style=flat" alt="Platform"></a>
+<a href="https://cocoapods.org/pods/UsergridSDK"><img src="https://img.shields.io/cocoapods/v/UsergridSDK.svg" alt="CocoaPods Compatible"></a></p>
<p>Usergrid SDK written in Swift </p>
<a href='#requirements' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='requirements'>Requirements</h2>
<blockquote>
-<p><strong>Embedded frameworks require a minimum deployment target of iOS 8.</strong></p>
+<p><strong>While the Usergrid SDK is written in Swift, the functionality remains compatible with Objective-C.</strong></p>
+
+<p><strong>Use <code>#import <UsergridSDK/UsergridSDK-Swift.h></code> in your Objective-C files to enable the use of the SDK.</strong></p>
</blockquote>
<ul>
-<li>iOS 8.0+</li>
+<li>iOS 8.0+ / Mac OS X 10.11+ / tvOS 9.1+ / watchOS 2.1+</li>
<li>Xcode 7.1+</li>
</ul>
<a href='#installation' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='installation'>Installation</h2>
+
+<blockquote>
+<p><strong>Embedded frameworks require a minimum deployment target of iOS 8 or OS X Mavericks (10.9).</strong></p>
+</blockquote>
<a href='#cocoapods' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='cocoapods'>CocoaPods</h3>
<blockquote>
@@ -200,11 +204,11 @@
<ul>
<li>Add UsergridSDK as a git submodule by running the following command:</li>
</ul>
-<pre class="highlight shell"><code><span class="gp">$ </span>git submodule add https://github.com/RobertWalsh/UsergridSDK.git
+<pre class="highlight shell"><code><span class="gp">$ </span>git submodule add https://github.com/apache/usergrid
</code></pre>
<ul>
-<li>Open the new <code>UsergridSDK</code> folder, and drag the <code>UsergridSDK.xcodeproj</code> into the Project Navigator of your application’s Xcode project.</li>
+<li>Open the <code>sdks/swift</code> folder, and drag the <code>UsergridSDK.xcodeproj</code> into the Project Navigator of your application’s Xcode project.</li>
</ul>
<blockquote>
@@ -227,32 +231,685 @@
<p>The documentation for this library is available <a href="http://cocoadocs.org/docsets/UsergridSDK">here</a>.</p>
<a href='#initialization' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='initialization'>Initialization</h2>
-<p>The <code>Usergrid</code> class acts as a static shared instance manager for the <code>UsergridClient</code> class.</p>
+<p>There are two different ways of initializing the Usergrid Swift SDK: </p>
+
+<ol>
+<li>The singleton pattern is both convenient and enables the developer to use a globally available and always-initialized instance of Usergrid.</li>
+</ol>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">initSharedInstance</span><span class="p">(</span><span class="nv">orgId</span><span class="p">:</span> <span class="s">"orgId"</span><span class="p">,</span> <span class="nv">appId</span><span class="p">:</span> <span class="s">"appId"</span><span class="p">)</span>
+</code></pre>
+
+<ol>
+<li>The Instance pattern enables the developer to manage instances of the Usergrid client independently and in an isolated fashion. The primary use-case for this is when an application connects to multiple Usergrid targets.</li>
+</ol>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">client</span> <span class="o">=</span> <span class="kt">UsergridClient</span><span class="p">(</span><span class="nv">orgId</span><span class="p">:</span> <span class="s">"orgId"</span><span class="p">,</span> <span class="nv">appId</span><span class="p">:</span> <span class="s">"appId"</span><span class="p">)</span>
+</code></pre>
+
+<p><em>Note: Examples in this readme assume you are using the <code>Usergrid</code> shared instance. If you’ve implemented the instance pattern instead, simply replace <code>Usergrid</code> with your client instance variable.</em></p>
+<a href='#push_notifications' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='push_notifications'>Push Notifications</h2>
+
+<p><em>Note: You must have an Apple Developer account along with valid provisioning profiles set in order to receive push notifications.</em></p>
+
+<p>In order to utilize Usergrid push notifications, you must register the device with an Usergrid push notifier identifier.</p>
+
+<blockquote>
+<p>For a more thorough example of recieving push notifications and sending push notifications (from the device) refer to the Push sample app located in the <code>/Samples</code> folder.</p>
+</blockquote>
+
+<p>The following code snippet shows how you would register for push notifications and apply the push token within the application delegate.</p>
+<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">UsergridSDK</span>
+
+<span class="kd">@UIApplicationMain</span> <span class="kd">class</span> <span class="kt">AppDelegate</span><span class="p">:</span> <span class="kt">UIResponder</span><span class="p">,</span> <span class="kt">UIApplicationDelegate</span> <span class="p">{</span>
+
+ <span class="kd">func</span> <span class="nf">application</span><span class="p">(</span><span class="nv">application</span><span class="p">:</span> <span class="kt">UIApplication</span><span class="p">,</span> <span class="n">didFinishLaunchingWithOptions</span> <span class="nv">launchOptions</span><span class="p">:</span> <span class="p">[</span><span class="kt">NSObject</span><span class="p">:</span> <span class="kt">AnyObject</span><span class="p">]?)</span> <span class="o">-></span> <span class="kt">Bool</span> <span class="p">{</span>
+
+ <span class="c1">// Initialize the shared instance of Usergrid.</span>
+ <span class="kt">Usergrid</span><span class="o">.</span><span class="nf">initSharedInstance</span><span class="p">(</span><span class="nv">orgId</span><span class="p">:</span><span class="s">"orgId"</span><span class="p">,</span> <span class="nv">appId</span><span class="p">:</span> <span class="s">"appId"</span><span class="p">)</span>
+
+ <span class="c1">// Register for APN</span>
+ <span class="n">application</span><span class="o">.</span><span class="nf">registerUserNotificationSettings</span><span class="p">(</span><span class="kt">UIUserNotificationSettings</span><span class="p">(</span> <span class="nv">forTypes</span><span class="p">:</span> <span class="p">[</span><span class="o">.</span><span class="kt">Alert</span><span class="p">,</span> <span class="o">.</span><span class="kt">Badge</span><span class="p">,</span> <span class="o">.</span><span class="kt">Sound</span><span class="p">],</span> <span class="nv">categories</span><span class="p">:</span> <span class="kc">nil</span><span class="p">))</span>
+ <span class="n">application</span><span class="o">.</span><span class="nf">registerForRemoteNotifications</span><span class="p">()</span>
+
+ <span class="k">return</span> <span class="kc">true</span>
+ <span class="p">}</span>
+
+ <span class="kd">func</span> <span class="nf">application</span><span class="p">(</span><span class="nv">application</span><span class="p">:</span> <span class="kt">UIApplication</span><span class="p">,</span> <span class="n">didRegisterForRemoteNotificationsWithDeviceToken</span> <span class="nv">deviceToken</span><span class="p">:</span> <span class="kt">NSData</span><span class="p">)</span> <span class="p">{</span>
+ <span class="kt">Usergrid</span><span class="o">.</span><span class="nf">applyPushToken</span><span class="p">(</span><span class="n">deviceToken</span><span class="p">,</span> <span class="nv">notifierID</span><span class="p">:</span> <span class="s">"notifierId"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// The push notification is now added to Usergrid for this device and this device will now be able to recieve notifications.</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#restful_operations' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='restful_operations'>RESTful operations</h2>
+
+<p>When making any RESTful call, a <code>type</code> parameter (or <code>path</code>) is always required. Whether you specify this as an argument or in an object as a parameter is up to you.</p>
+<a href='#get' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='get'>GET</h3>
+
+<ul>
+<li>To get entities in a collection:</li>
+</ul>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"collection"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="k">var</span> <span class="nv">entities</span><span class="p">:</span> <span class="p">[</span><span class="kt">UsergridEntity</span><span class="p">]?</span> <span class="o">=</span> <span class="n">response</span><span class="o">.</span><span class="n">entities</span>
+<span class="p">}</span>
+</code></pre>
+
+<ul>
+<li>To get a specific entity in a collection by uuid or name:</li>
+</ul>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"collection"</span><span class="p">,</span> <span class="nv">uuidOrName</span><span class="p">:</span><span class="s">"<uuid-or-name>"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="k">var</span> <span class="nv">entity</span><span class="p">:</span> <span class="kt">UsergridEntity</span><span class="p">?</span> <span class="o">=</span> <span class="n">response</span><span class="o">.</span><span class="n">entity</span><span class="p">?</span>
+<span class="p">}</span>
+</code></pre>
+
+<ul>
+<li>To get specific entities in a collection by passing a <code>UsergridQuery</code> object:</li>
+</ul>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">gt</span><span class="p">(</span><span class="s">"weight"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="mf">2.4</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">contains</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"bl*"</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">not</span><span class="p">()</span>
+ <span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"blue"</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">or</span><span class="p">()</span>
+ <span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"orange"</span><span class="p">)</span>
+
+<span class="c1">// this will build out the following query:</span>
+<span class="c1">// select * where weight > 2.4 and color contains 'bl*' and not color = 'blue' or color = 'orange'</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="n">query</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="k">var</span> <span class="nv">entities</span><span class="p">:</span> <span class="p">[</span><span class="kt">UsergridEntity</span><span class="p">]?</span> <span class="o">=</span> <span class="n">response</span><span class="o">.</span><span class="n">entities</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#post_and_put' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='post_and_put'>POST and PUT</h3>
+
+<p>POST and PUT requests both require a JSON body payload. You can pass either a Swift object or a <code>UsergridEntity</code> instance. While the former works in principle, best practise is to use a <code>UsergridEntity</code> wherever practical. When an entity has a uuid or name property and already exists on the server, use a PUT request to update it. If it does not, use POST to create it.</p>
+
+<ul>
+<li>To create a new entity in a collection (<strong>POST</strong>):</li>
+</ul>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">entity</span> <span class="o">=</span> <span class="kt">UsergridEntity</span><span class="p">(</span><span class="nv">type</span><span class="p">:</span> <span class="s">"restaurant"</span><span class="p">,</span> <span class="nv">propertyDict</span><span class="p">:</span> <span class="p">[</span><span class="s">"restaurant"</span><span class="p">:</span> <span class="s">"Dino's Deep Dish"</span><span class="p">,</span><span class="s">"cuisine"</span><span class="p">:</span> <span class="s">"pizza"</span><span class="p">])</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">POST</span><span class="p">(</span><span class="n">entity</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entity should now have a uuid property and be created</span>
+<span class="p">}</span>
+
+<span class="c1">// you can also POST an array of entities:</span>
+
+<span class="k">var</span> <span class="nv">entities</span> <span class="o">=</span> <span class="p">[</span><span class="kt">UsergridEntity</span><span class="p">(</span><span class="nv">type</span><span class="p">:</span> <span class="s">"restaurant"</span><span class="p">,</span> <span class="nv">propertyDict</span><span class="p">:[</span><span class="s">"restaurant"</span><span class="p">:</span> <span class="s">"Dino's Deep Dish"</span><span class="p">,</span><span class="s">"cuisine"</span><span class="p">:</span> <span class="s">"pizza"</span><span class="p">]),</span>
+ <span class="kt">UsergridEntity</span><span class="p">(</span><span class="nv">type</span><span class="p">:</span> <span class="s">"restaurant"</span><span class="p">,</span> <span class="nv">propertyDict</span><span class="p">:[</span><span class="s">"restaurant"</span><span class="p">:</span> <span class="s">"Pizza da Napoli"</span><span class="p">,</span><span class="s">"cuisine"</span><span class="p">:</span> <span class="s">"pizza"</span><span class="p">])]</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">POST</span><span class="p">(</span><span class="n">entities</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// response.entities should now contain now valid posted entities.</span>
+<span class="p">}</span>
+</code></pre>
+
+<ul>
+<li>To update an entity in a collection (<strong>PUT</strong>):</li>
+</ul>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">entity</span> <span class="o">=</span> <span class="kt">UsergridEntity</span><span class="p">(</span><span class="nv">type</span><span class="p">:</span> <span class="s">"restaurant"</span><span class="p">,</span> <span class="nv">propertyDict</span><span class="p">:[</span><span class="s">"restaurant"</span><span class="p">:</span> <span class="s">"Dino's Deep Dish"</span><span class="p">,</span> <span class="s">"cuisine"</span><span class="p">:</span> <span class="s">"pizza"</span><span class="p">])</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">POST</span><span class="p">(</span><span class="n">entity</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="k">if</span> <span class="k">let</span> <span class="nv">responseEntity</span> <span class="o">=</span> <span class="n">response</span><span class="o">.</span><span class="n">entity</span> <span class="p">{</span>
+ <span class="n">responseEntity</span><span class="p">[</span><span class="s">"owner"</span><span class="p">]</span> <span class="o">=</span> <span class="s">"Mia Carrara"</span>
+ <span class="kt">Usergrid</span><span class="o">.</span><span class="kt">PUT</span><span class="p">(</span><span class="n">responseEntity</span><span class="p">)</span> <span class="p">{</span> <span class="p">(</span><span class="n">response</span><span class="p">)</span> <span class="o">-></span> <span class="kt">Void</span> <span class="k">in</span>
+ <span class="c1">// entity now has the property 'owner'</span>
+ <span class="p">}</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+
+<span class="c1">// or update a set of entities by passing a UsergridQuery object</span>
+
+<span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"restaurants"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"cuisine"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"italian"</span><span class="p">)</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">PUT</span><span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="nv">jsonBody</span><span class="p">:</span> <span class="p">[</span><span class="s">"keywords"</span><span class="p">:[</span><span class="s">"pasta"</span><span class="p">]])</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+
+ <span class="cm">/* the first 10 entities matching this query criteria will be updated:
+ e.g.:
+ [
+ {
+ "type": "restaurant",
+ "restaurant": "Il Tarazzo",
+ "cuisine": "italian",
+ "keywords": ["pasta"]
+ },
+ {
+ "type": "restaurant",
+ "restaurant": "Cono Sur Pizza & Pasta",
+ "cuisine": "italian",
+ "keywords": ["pasta"]
+ }
+ ]
+ */</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#delete' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='delete'>DELETE</h3>
+
+<p>DELETE requests require either a specific entity or a <code>UsergridQuery</code> object to be passed as an argument.</p>
+
+<ul>
+<li>To delete a specific entity in a collection by uuid or name:</li>
+</ul>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="kt">DELETE</span><span class="p">(</span><span class="s">"collection"</span><span class="p">,</span> <span class="nv">uuidOrName</span><span class="p">:</span> <span class="s">"<uuid-or-name>"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// if successful, entity will now be deleted</span>
+<span class="p">})</span>
+</code></pre>
+
+<ul>
+<li>To specific entities in a collection to delete by passing a <code>UsergridQuery</code> object:</li>
+</ul>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"black"</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">or</span><span class="p">()</span>
+ <span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"white"</span><span class="p">)</span>
+
+<span class="c1">// this will build out the following query:</span>
+<span class="c1">// select * where color = 'black' or color = 'white'</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">DELETE</span><span class="p">(</span><span class="n">query</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// the first 10 entities matching this query criteria will be deleted</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#entity_operations_and_convenience_methods' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='entity_operations_and_convenience_methods'>Entity operations and convenience methods</h2>
+
+<p><code>UsergridEntity</code> has a number of helper/convenience methods to make working with entities more convenient.</p>
+<a href='#reload' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='reload'>reload()</h3>
+
+<p>Reloads the entity from the server:</p>
+<pre class="highlight swift"><code><span class="n">entity</span><span class="o">.</span><span class="nf">reload</span><span class="p">()</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entity is now reloaded from the server</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#save' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='save'>save()</h3>
+
+<p>Saves (or creates) the entity on the server:</p>
+<pre class="highlight swift"><code><span class="n">entity</span><span class="p">[</span><span class="s">"aNewProperty"</span><span class="p">]</span> <span class="o">=</span> <span class="s">"A new value"</span>
+<span class="n">entity</span><span class="o">.</span><span class="nf">save</span><span class="p">()</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entity is now updated on the server</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#remove' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='remove'>remove()</h3>
+
+<p>Deletes the entity from the server:</p>
+<pre class="highlight swift"><code><span class="n">entity</span><span class="o">.</span><span class="nf">remove</span><span class="p">()</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entity is now deleted on the server and the local instance should be destroyed</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#authentication_current_user_and_auth_fallback' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='authentication_current_user_and_auth_fallback'>Authentication, current user, and auth-fallback</h2>
+<a href='#appauth_and_authenticateapp' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='appauth_and_authenticateapp'>appAuth and authenticateApp()</h3>
+
+<p><code>Usergrid</code> can use the app client ID and secret that were passed upon initialization and automatically retrieve an app-level token for these credentials.</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">setAppAuth</span><span class="p">(</span><span class="s">"<client-id>"</span><span class="p">,</span> <span class="s">"<client-secret>"</span><span class="p">)</span>
+<span class="kt">Usergrid</span><span class="o">.</span><span class="nf">authenticateApp</span><span class="p">()</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// Usergrid.appAuth is authenticated automatically when this call is successful</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#currentuser_userauth_and_authenticateuser' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='currentuser_userauth_and_authenticateuser'>currentUser, userAuth, and authenticateUser()</h3>
+
+<p><code>Usergrid</code> has a special <code>currentUser</code> property. </p>
+
+<blockquote>
+<p>The current user is stored within the keychain so app relaunches will persist the user’s login and token information. To adjust this feature edit the <code>Usergrid.persistCurrentUserInKeychain</code> property upon initialization.</p>
+</blockquote>
+
+<p>By default, when calling <code>authenticateUser()</code>, <code>.currentUser</code> will be set to this user if the authentication flow is successful.</p>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">userAuth</span> <span class="o">=</span> <span class="kt">UsergridUserAuth</span><span class="p">(</span><span class="nv">username</span><span class="p">:</span> <span class="s">"<username>"</span><span class="p">,</span> <span class="nv">password</span><span class="p">:</span> <span class="s">"<password>"</span><span class="p">)</span>
+<span class="kt">Usergrid</span><span class="o">.</span><span class="nf">authenticateUser</span><span class="p">(</span><span class="n">userAuth</span><span class="p">)</span> <span class="p">{</span> <span class="n">auth</span><span class="p">,</span> <span class="n">user</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
+ <span class="c1">// Usergrid.currentUser is set to the authenticated user and the token is stored within that context</span>
+<span class="p">}</span>
+</code></pre>
+
+<p>If you want to utilize authenticateUser without setting as the current user, simply pass a <code>false</code> boolean value as the second parameter:</p>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">userAuth</span> <span class="o">=</span> <span class="kt">UsergridUserAuth</span><span class="p">(</span><span class="nv">username</span><span class="p">:</span> <span class="s">"<username>"</span><span class="p">,</span> <span class="nv">password</span><span class="p">:</span> <span class="s">"<password>"</span><span class="p">)</span>
+<span class="kt">Usergrid</span><span class="o">.</span><span class="nf">authenticateUser</span><span class="p">(</span><span class="n">userAuth</span><span class="p">,</span><span class="nv">setAsCurrentUser</span><span class="p">:</span> <span class="kc">false</span><span class="p">)</span> <span class="p">{</span> <span class="n">auth</span><span class="p">,</span> <span class="n">user</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
+ <span class="c1">// user is authenticated but Usergrid.currentUser is not set.</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#authfallback' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='authfallback'>authFallback</h3>
+
+<p>Auth-fallback defines what the client should do when a user token is not present. </p>
+
+<p>By default, <code>Usergrid.authFallback</code> is set to <code>.None</code>, whereby when a token is <em>not</em> present, an API call will be performed unauthenticated. </p>
+
+<p>If instead <code>Usergrid.authFallback</code> is set to <code>.App</code>, the API call will instead be performed using client credentials, <em>if</em> they’re available (i.e. <code>authenticateApp()</code> was performed at some point). </p>
+<a href='#usingauth' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='usingauth'>usingAuth()</h3>
+
+<p>At times it is desireable to have complete, granular control over the authentication context of an API call. </p>
+
+<p>To facilitate this, the passthrough function <code>.usingAuth()</code> allows you to pre-define the auth context of the next API call.</p>
+<pre class="highlight swift"><code><span class="c1">// assume Usergrid.authFallback = .None</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="nf">usingAuth</span><span class="p">(</span><span class="kt">Usergrid</span><span class="o">.</span><span class="n">appAuth</span><span class="o">!</span><span class="p">)</span><span class="o">.</span><span class="kt">POST</span><span class="p">(</span><span class="s">"roles/guest/permissions"</span><span class="p">,</span> <span class="nv">jsonBody</span><span class="p">:</span> <span class="p">[</span><span class="s">"permission"</span> <span class="p">:</span> <span class="s">"get,post,put,delete:/**"</span><span class="p">]</span> <span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// here we've temporarily used the client credentials to modify permissions</span>
+ <span class="c1">// subsequent calls will not use this auth context</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#user_operations_and_convenience_methods' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='user_operations_and_convenience_methods'>User operations and convenience methods</h2>
+
+<p><code>UsergridUser</code> has a number of helper/convenience methods to make working with user entities more convenient. If you are <em>not</em> utilizing the <code>Usergrid</code> shared instance, you must pass an instance of <code>UsergridClient</code> as the first argument to any of these helper methods.</p>
+<a href='#create' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='create'>create()</h3>
+
+<p>Creating a new user:</p>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">user</span> <span class="o">=</span> <span class="kt">UsergridUser</span><span class="p">(</span><span class="nv">username</span><span class="p">:</span> <span class="s">"username"</span><span class="p">,</span> <span class="nv">password</span><span class="p">:</span> <span class="s">"password"</span><span class="p">)</span>
+<span class="n">user</span><span class="o">.</span><span class="nf">create</span><span class="p">()</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// user has now been created and should have a valid uuid</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#login' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='login'>login()</h3>
+
+<p>A simpler means of retrieving a user-level token:</p>
+<pre class="highlight swift"><code><span class="n">user</span><span class="o">.</span><span class="nf">login</span><span class="p">(</span><span class="s">"username"</span><span class="p">,</span> <span class="nv">password</span><span class="p">:</span> <span class="s">"password"</span><span class="p">)</span> <span class="p">{</span> <span class="n">auth</span><span class="p">,</span> <span class="n">user</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
+ <span class="c1">// user is now logged in</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#logout' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='logout'>logout()</h3>
+
+<p>Logs out the selected user. You can also use this convenience method on <code>Usergrid.currentUser</code>.</p>
+<pre class="highlight swift"><code><span class="n">user</span><span class="o">.</span><span class="nf">logout</span><span class="p">()</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// user is now logged out</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#resetpassword' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='resetpassword'>resetPassword()</h3>
+
+<p>Resets the password for the selected user.</p>
+<pre class="highlight swift"><code><span class="n">user</span><span class="o">.</span><span class="nf">resetPassword</span><span class="p">(</span><span class="s">"oldPassword"</span><span class="p">,</span> <span class="nv">new</span><span class="p">:</span> <span class="s">"newPassword"</span><span class="p">)</span> <span class="p">{</span> <span class="n">error</span><span class="p">,</span> <span class="n">didSucceed</span> <span class="k">in</span>
+ <span class="c1">// if it was done correctly, the new password will be changed</span>
+ <span class="c1">// 'didSucceed' is a boolean value that indicates whether it was changed successfully</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#usergriduser_checkavailable' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='usergriduser_checkavailable'>UsergridUser.CheckAvailable()</h3>
+
+<p>This is a class (static) method that allows you to check whether a username or email address is available or not.</p>
+<pre class="highlight swift"><code><span class="kt">UsergridUser</span><span class="o">.</span><span class="nf">checkAvailable</span><span class="p">(</span><span class="s">"email"</span><span class="p">,</span> <span class="nv">username</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span> <span class="p">{</span> <span class="n">error</span><span class="p">,</span> <span class="n">available</span> <span class="k">in</span>
+ <span class="c1">// 'available' == whether an email already exists for a user</span>
+<span class="p">}</span>
+
+<span class="kt">UsergridUser</span><span class="o">.</span><span class="nf">checkAvailable</span><span class="p">(</span><span class="kc">nil</span><span class="p">,</span> <span class="nv">username</span><span class="p">:</span> <span class="s">"username"</span><span class="p">)</span> <span class="p">{</span> <span class="n">error</span><span class="p">,</span> <span class="n">available</span> <span class="k">in</span>
+ <span class="c1">// 'available' == whether an username already exists for a user</span>
+<span class="p">}</span>
+
+<span class="kt">UsergridUser</span><span class="o">.</span><span class="nf">checkAvailable</span><span class="p">(</span><span class="s">"email"</span><span class="p">,</span> <span class="nv">username</span><span class="p">:</span> <span class="s">"username"</span><span class="p">)</span> <span class="p">{</span> <span class="n">error</span><span class="p">,</span> <span class="n">available</span> <span class="k">in</span>
+ <span class="c1">// 'available' == whether an email or username already exist for a user</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#querying_and_filtering_data' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='querying_and_filtering_data'>Querying and filtering data</h2>
+<a href='#usergridquery_initialization' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='usergridquery_initialization'>UsergridQuery initialization</h3>
+
+<p>The <code>UsergridQuery</code> class allows you to build out complex query filters using the Usergrid <a href="http://docs.apigee.com/app-services/content/querying-your-data">query syntax</a>.</p>
+
+<p>The first parameter of the <code>UsergridQuery</code> builder pattern should be the collection (or type) you intend to query. You can either pass this as an argument, or as the first builder object:</p>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span>
+<span class="c1">// or</span>
+<span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">()</span><span class="o">.</span><span class="nf">collection</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span>
+</code></pre>
+
+<p>You then can layer on additional queries:</p>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">gt</span><span class="p">(</span><span class="s">"weight"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="mf">2.4</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">contains</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="s">"bl*"</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">not</span><span class="p">()</span>
+ <span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"white"</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">or</span><span class="p">()</span>
+ <span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"orange"</span><span class="p">)</span>
+</code></pre>
+
+<p>You can also adjust the number of results returned:</p>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="s">"black"</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">limit</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>
+
+<span class="c1">// returns a maximum of 100 entiteis</span>
+</code></pre>
+
+<p>And sort the results:</p>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="s">"black"</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">limit</span><span class="p">(</span><span class="mi">100</span><span class="p">)</span>
+ <span class="o">.</span><span class="nf">asc</span><span class="p">(</span><span class="s">"name"</span><span class="p">)</span>
+
+<span class="c1">// sorts by 'name', ascending</span>
+</code></pre>
+
+<p>And you can do geo-location queries:</p>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"devices"</span><span class="p">)</span><span class="o">.</span><span class="nf">locationWithin</span><span class="p">(</span><span class="o"><</span><span class="n">distance</span><span class="o">></span><span class="p">,</span> <span class="nv">latitude</span><span class="p">:</span> <span class="o"><</span><span class="n">lat</span><span class="o">></span><span class="p">,</span> <span class="nv">longitude</span><span class="p">:</span> <span class="o"><</span><span class="n">long</span><span class="o">></span><span class="p">)</span>
+</code></pre>
+<a href='#using_a_query_in_a_request' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='using_a_query_in_a_request'>Using a query in a request</h3>
+
+<p>Queries can be passed as parameters to GET, PUT, and DELETE requests:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"type"</span><span class="p">,</span> <span class="nv">query</span><span class="p">:</span> <span class="n">query</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// Gets entities of a given type matching the query.</span>
+<span class="p">}</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">PUT</span><span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="nv">jsonBody</span><span class="p">:</span> <span class="p">[</span><span class="s">"aNewProperty"</span><span class="p">:</span><span class="s">"A new value"</span><span class="p">])</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// Updates the entities matching the query with the new property.</span>
+<span class="p">}</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">DELETE</span><span class="p">(</span><span class="n">query</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// Deletes entities of a given type matching the query.</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#list_of_query_builder_objects' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='list_of_query_builder_objects'>List of query builder objects</h3>
+
+<p><code>type("string")</code></p>
+
+<blockquote>
+<p>The collection name to query</p>
+</blockquote>
+
+<p><code>collection("string")</code></p>
+
+<blockquote>
+<p>An alias for <code>type</code></p>
+</blockquote>
+
+<p><code>eq("key", value: "value")</code> or
+<code>equals("key", value: "value")</code> or
+<code>filter("key", value: "value")</code> </p>
+
+<blockquote>
+<p>Equal to (e.g. <code>where color = 'black'</code>)</p>
+</blockquote>
+
+<p><code>contains("key", value: "value")</code> or
+<code>containsString("key", value: "value")</code> or
+<code>containsWord("key", value: "value")</code></p>
+
+<blockquote>
+<p>Contains a string (e.g.<code>where color contains 'bl*'</code>)</p>
+</blockquote>
+
+<p><code>gt("key", value: "value")</code> or
+<code>greaterThan("key", value: "value")</code></p>
+
+<blockquote>
+<p>Greater than (e.g. <code>where weight > 2.4</code>)</p>
+</blockquote>
+
+<p><code>gte("key", value: "value")</code> or
+<code>greaterThanOrEqual("key", value: "value")</code></p>
+
+<blockquote>
+<p>Greater than or equal to (e.g. <code>where weight >= 2.4</code>)</p>
+</blockquote>
+
+<p><code>lt("key", value: "value")</code> or <code>lessThan("key", value: "value")</code></p>
+
+<blockquote>
+<p>Less than (e.g. <code>where weight < 2.4</code>)</p>
+</blockquote>
+
+<p><code>lte("key", value: "value")</code> or <code>lessThanOrEqual("key", value: "value")</code></p>
+
+<blockquote>
+<p>Less than or equal to (e.g. <code>where weight <= 2.4</code>)</p>
+</blockquote>
+
+<p><code>not()</code></p>
+
+<blockquote>
+<p>Negates the next block in the builder pattern, e.g.:</p>
+</blockquote>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">not</span><span class="p">()</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="s">"black"</span><span class="p">)</span>
+<span class="c1">// select * from cats where not color = 'black'</span>
+</code></pre>
+
+<p><code>and()</code></p>
+
+<blockquote>
+<p>Joins two queries by requiring both of them. <code>and</code> is also implied when joining two queries <em>without</em> an operator. E.g.:</p>
+</blockquote>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"black"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"fur"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"longHair"</span><span class="p">)</span>
+<span class="c1">// is identical to:</span>
+<span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"black"</span><span class="p">)</span><span class="o">.</span><span class="nf">and</span><span class="p">()</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"fur"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span><span class="s">"longHair"</span><span class="p">)</span>
+</code></pre>
+
+<p><code>or()</code></p>
+
+<blockquote>
+<p>Joins two queries by requiring only one of them. <code>or</code> is never implied. e.g.:</p>
+</blockquote>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">(</span><span class="s">"cats"</span><span class="p">)</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span><span class="nv">value</span><span class="p">:</span> <span class="s">"black"</span><span class="p">)</span><span class="o">.</span><span class="nf">or</span><span class="p">()</span><span class="o">.</span><span class="nf">eq</span><span class="p">(</span><span class="s">"color"</span><span class="p">,</span> <span class="nv">value</span><span class="p">:</span> <span class="s">"white"</span><span class="p">)</span>
+</code></pre>
+
+<blockquote>
+<p>When using <code>or()</code> and <code>and()</code> operators, <code>and()</code> joins will take precedence over <code>or()</code> joins. You can read more about query operators and precedence <a href="http://docs.apigee.com/api-baas/content/supported-query-operators-data-types">here</a>.</p>
+</blockquote>
+
+<p><code>locationWithin(distanceInMeters, latitude: latitude, longitude: longitude)</code></p>
+
+<blockquote>
+<p>Returns entities which have a location within the specified radius. Arguments can be <code>float</code> or <code>int</code>.</p>
+</blockquote>
+
+<p><code>asc("key")</code> or <code>ascending("key")</code></p>
+
+<blockquote>
+<p>Sorts the results by the specified property, ascending</p>
+</blockquote>
+
+<p><code>desc("key")</code> or <code>descending("key")</code></p>
+
+<blockquote>
+<p>Sorts the results by the specified property, descending</p>
+</blockquote>
+
+<p><code>sort("key", value: .Asc)</code></p>
+
+<blockquote>
+<p>Sorts the results by the specified property, in the specified <code>UsergridQuerySortOrder</code> (<code>.Asc</code> or <code>.Desc</code>).</p>
+</blockquote>
+
+<p><code>limit(int)</code></p>
+
+<blockquote>
+<p>The maximum number of entities to return</p>
+</blockquote>
+
+<p><code>cursor("string")</code></p>
+
+<blockquote>
+<p>A pagination cursor string</p>
+</blockquote>
+
+<p><code>fromString("query string")</code></p>
+
+<blockquote>
+<p>A special builder property that allows you to input a pre-defined query string. All builder properties will be ignored when this property is defined. For example:</p>
+</blockquote>
+<pre class="highlight swift"><code><span class="k">var</span> <span class="nv">query</span> <span class="o">=</span> <span class="kt">UsergridQuery</span><span class="p">()</span><span class="o">.</span><span class="nf">fromString</span><span class="p">(</span><span class="s">"select * where color = 'black' order by name asc"</span><span class="p">)</span>
+</code></pre>
+<a href='#usergridresponse_object' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='usergridresponse_object'>UsergridResponse object</h2>
+
+<p><code>UsergridResponse</code> is the core class that handles both successful and unsuccessful HTTP responses from Usergrid. </p>
+
+<p>If a request is successful, any entities returned in the response will be automatically parsed into <code>UsergridEntity</code> objects and pushed to the <code>entities</code> property.</p>
+
+<p>If a request fails, the <code>error</code> property will contain information about the problem encountered.</p>
+<a href='#ok' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='ok'>ok</h3>
+
+<p>You can check <code>UsergridResponse.ok</code>, a <code>Bool</code> value, to see if the response was successful. Any status code <code>< 400</code> returns true.</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"collection"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="k">if</span> <span class="n">response</span><span class="o">.</span><span class="n">ok</span> <span class="p">{</span>
+ <span class="c1">// woo!</span>
+ <span class="p">}</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#entity_entities_user_users_first_last' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='entity_entities_user_users_first_last'>entity, entities, user, users, first, last</h3>
+
+<p>Depending on the call you make, any entities returned in the response will be automatically parsed into <code>UsergridEntity</code> objects and pushed to the <code>entities</code> property. If you’re querying the <code>users</code> collection, these will also be <code>UsergridUser</code> objects, a subclass of <code>UsergridEntity</code>.</p>
+
+<ul>
+<li><p><code>.first</code> returns the first entity in an array of entities; <code>.entity</code> is an alias to <code>.first</code>. If there are no entities, both of these will be undefined.</p></li>
+<li><p><code>.last</code> returns the last entity in an array of entities; if there is only one entity in the array, this will be the same as <code>.first</code> <em>and</em> <code>.entity</code>, and will be undefined if there are no entities in the response.</p></li>
+<li><p><code>.entities</code> will either be an array of entities in the response, or an empty array.</p></li>
+<li><p><code>.user</code> is a special alias for <code>.entity</code> for when querying the <code>users</code> collection. Instead of being a <code>UsergridEntity</code>, it will be its subclass, <code>UsergridUser</code>.</p></li>
+<li><p><code>.users</code> is the same as <code>.user</code>, though behaves as <code>.entities</code> does by returning either an array of UsergridUser objects or an empty array.</p></li>
+</ul>
+
+<p>Examples:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"collection"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// you can access:</span>
+ <span class="c1">// response.entities (the returned entities)</span>
+ <span class="c1">// response.first (the first entity)</span>
+ <span class="c1">// response.entity (same as response.first)</span>
+ <span class="c1">// response.last (the last entity returned)</span>
+<span class="p">}</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"collection"</span><span class="p">,</span> <span class="nv">uuidOrName</span><span class="p">:</span><span class="s">"<uuid-or-name>"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// you can access:</span>
+ <span class="c1">// response.entity (the returned entity) </span>
+ <span class="c1">// response.entities (containing only the returned entity)</span>
+ <span class="c1">// response.first (same as response.entity)</span>
+ <span class="c1">// response.last (same as response.entity)</span>
+<span class="p">}</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"users"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// you can access:</span>
+ <span class="c1">// response.users (the returned users)</span>
+ <span class="c1">// response.entities (same as response.users)</span>
+ <span class="c1">// response.user (the first user) </span>
+ <span class="c1">// response.entity (same as response.user) </span>
+ <span class="c1">// response.first (same as response.user) </span>
+ <span class="c1">// response.last (the last user)</span>
+<span class="p">}</span>
+
+<span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"users"</span><span class="p">,</span> <span class="nv">uuidOrName</span><span class="p">:</span><span class="s">"<uuid-or-name>"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// you can access;</span>
+ <span class="c1">// response.users (containing only the one user)</span>
+ <span class="c1">// response.entities (same as response.users)</span>
+ <span class="c1">// response.user (the returned user) </span>
+ <span class="c1">// response.entity (same as response.user) </span>
+ <span class="c1">// response.first (same as response.user) </span>
+ <span class="c1">// response.last (same as response.user) </span>
+<span class="p">}</span>
+</code></pre>
+<a href='#connections' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='connections'>Connections</h2>
+
+<p>Connections can be managed using <code>Usergrid.connect()</code>, <code>Usergrid.disconnect()</code>, and <code>Usergrid.getConnections()</code>, or entity convenience methods of the same name. </p>
+
+<p>When retrieving connections via <code>Usergrid.getConnections()</code>, you can pass in a optional <code>UsergridQuery</code> object in order to filter the connectioned entities returned.</p>
+<a href='#connect' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='connect'>Connect</h3>
+
+<p>Create a connection between two entities:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">connect</span><span class="p">(</span><span class="n">entity1</span><span class="p">,</span> <span class="nv">relationship</span><span class="p">:</span> <span class="s">"relationship"</span><span class="p">,</span> <span class="nv">to</span><span class="p">:</span> <span class="n">entity2</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entity1 now has an outbound connection to entity2</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#retrieve_connections' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='retrieve_connections'>Retrieve Connections</h3>
+
+<p>Retrieve outbound connections:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">getConnections</span><span class="p">(</span><span class="o">.</span><span class="kt">Out</span><span class="p">,</span> <span class="nv">entity</span><span class="p">:</span> <span class="n">entity1</span><span class="p">,</span> <span class="nv">relationship</span><span class="p">:</span> <span class="s">"relationship"</span><span class="p">,</span> <span class="nv">query</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entities is an array of entities that entity1 is connected to via 'relationship'</span>
+ <span class="c1">// in this case, we'll see entity2 in the array</span>
+<span class="p">}</span>
+</code></pre>
+
+<p>Retrieve inbound connections:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">getConnections</span><span class="p">(</span><span class="o">.</span><span class="kt">In</span><span class="p">,</span> <span class="nv">entity</span><span class="p">:</span> <span class="n">entity2</span><span class="p">,</span> <span class="nv">relationship</span><span class="p">:</span> <span class="s">"relationship"</span><span class="p">,</span> <span class="nv">query</span><span class="p">:</span> <span class="kc">nil</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entities is an array of entities that connect to entity2 via 'relationship'</span>
+ <span class="c1">// in this case, we'll see entity1 in the array</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#disconnect' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='disconnect'>Disconnect</h3>
+
+<p>Delete a connection between two entities:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">disconnect</span><span class="p">(</span><span class="n">entity1</span><span class="p">,</span> <span class="nv">relationship</span><span class="p">:</span> <span class="s">"relationship"</span><span class="p">,</span> <span class="nv">from</span><span class="p">:</span> <span class="n">entity2</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="c1">// entity1's outbound connection to entity2 has been destroyed</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#assets' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='assets'>Assets</h2>
+
+<p>Assets can be uploaded and downloaded either directly using <code>Usergrid.uploadAsset()</code> or <code>Usergrid.downloadAsset()</code>, or via <code>UsergridEntity</code> convenience methods with the same names. Before uploading an asset, you will need to initialize a <code>UsergridAsset</code> instance.</p>
+<a href='#initialization' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='initialization'>Initialization</h3>
+
+<p><em>Note: When initializing a <code>UsergridAsset</code> object specifying a file name is optional.</em></p>
+
+<ul>
+<li>Using NSData:</li>
+</ul>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">image</span> <span class="o">=</span> <span class="kt">UIImage</span><span class="p">(</span><span class="nv">contentsOfFile</span><span class="p">:</span> <span class="s">"path/to/image"</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">data</span> <span class="o">=</span> <span class="kt">UIImagePNGRepresentation</span><span class="p">(</span><span class="n">image</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">asset</span> <span class="o">=</span> <span class="kt">UsergridAsset</span><span class="p">(</span><span class="nv">fileName</span><span class="p">:</span><span class="s">"<file-name-or-nil>"</span><span class="p">,</span> <span class="nv">data</span><span class="p">:</span> <span class="n">data</span><span class="o">!</span><span class="p">,</span> <span class="nv">contentType</span><span class="p">:</span><span class="s">"image/png"</span><span class="p">)</span>
+</code></pre>
+
+<ul>
+<li>Using an UIImage object:</li>
+</ul>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">image</span> <span class="o">=</span> <span class="kt">UIImage</span><span class="p">(</span><span class="nv">contentsOfFile</span><span class="p">:</span> <span class="s">"path/to/image"</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">asset</span> <span class="o">=</span> <span class="kt">UsergridAsset</span><span class="p">(</span><span class="nv">fileName</span><span class="p">:</span><span class="s">"<file-name-or-nil>"</span><span class="p">,</span> <span class="nv">image</span><span class="p">:</span> <span class="n">image</span><span class="o">!</span><span class="p">,</span> <span class="nv">imageContentType</span><span class="p">:</span> <span class="o">.</span><span class="kt">Png</span><span class="p">)</span>
+</code></pre>
+
+<ul>
+<li>Using a file URL:</li>
+</ul>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">fileUrl</span> <span class="o">=</span> <span class="kt">NSURL</span><span class="p">(</span><span class="nv">string</span><span class="p">:</span> <span class="s">"local/path/to/file"</span><span class="p">)</span>
+<span class="k">if</span> <span class="n">fileUrl</span><span class="o">.</span><span class="nf">isFileReferenceURL</span><span class="p">()</span> <span class="p">{</span> <span class="c1">// This must be a file reference url.</span>
+ <span class="k">let</span> <span class="nv">asset</span> <span class="o">=</span> <span class="kt">UsergridAsset</span><span class="p">(</span><span class="nv">fileName</span><span class="p">:</span><span class="s">"<file-name-or-nil>"</span><span class="p">,</span> <span class="nv">fileUrl</span><span class="p">:</span> <span class="n">fileUrl</span><span class="o">!</span><span class="p">,</span> <span class="nv">contentType</span><span class="p">:</span><span class="s">"<content-type>"</span><span class="p">)</span>
+<span class="p">}</span>
+</code></pre>
+<a href='#uploading' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='uploading'>Uploading</h3>
+
+<p>Upload an image and connect it to an entity:</p>
+<pre class="highlight swift"><code><span class="k">let</span> <span class="nv">image</span> <span class="o">=</span> <span class="kt">UIImage</span><span class="p">(</span><span class="nv">contentsOfFile</span><span class="p">:</span> <span class="s">"path/to/image"</span><span class="p">)</span>
+<span class="k">let</span> <span class="nv">asset</span> <span class="o">=</span> <span class="kt">UsergridAsset</span><span class="p">(</span><span class="nv">fileName</span><span class="p">:</span><span class="s">"<file-name-or-nil>"</span><span class="p">,</span> <span class="nv">image</span><span class="p">:</span> <span class="n">image</span><span class="o">!</span><span class="p">,</span> <span class="nv">imageContentType</span><span class="p">:</span> <span class="o">.</span><span class="kt">Png</span><span class="p">)</span><span class="o">!</span>
+<span class="kt">Usergrid</span><span class="o">.</span><span class="nf">uploadAsset</span><span class="p">(</span><span class="n">entity</span><span class="p">,</span>
+ <span class="k">as</span><span class="nv">set</span><span class="p">:</span> <span class="k">asset</span><span class="p">,</span>
+ <span class="nv">progress</span><span class="p">:</span> <span class="p">{</span> <span class="n">bytesFinished</span><span class="p">,</span> <span class="n">bytesExpected</span> <span class="k">in</span>
+ <span class="c1">// Monitor the upload progress</span>
+ <span class="p">},</span>
+ <span class="nv">completion</span><span class="p">:</span> <span class="p">{</span> <span class="n">response</span><span class="p">,</span> <span class="k">asset</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
+ <span class="c1">// The asset is now uploaded to Usergrid and entity.asset == asset</span>
+<span class="p">})</span>
+</code></pre>
+<a href='#downloading' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h3 id='downloading'>Downloading</h3>
+
+<p>Download an image which is connected to an entity:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">downloadAsset</span><span class="p">(</span><span class="n">entity</span><span class="p">,</span>
+ <span class="nv">contentType</span><span class="p">:</span> <span class="s">"<expected-content-type>"</span><span class="p">,</span>
+ <span class="nv">progress</span><span class="p">:</span> <span class="p">{</span> <span class="n">bytesFinished</span><span class="p">,</span> <span class="n">bytesExpected</span> <span class="k">in</span>
+ <span class="c1">// Monitor the download progress</span>
+ <span class="p">},</span>
+ <span class="nv">completion</span><span class="p">:{</span> <span class="k">asset</span><span class="p">,</span> <span class="n">error</span> <span class="k">in</span>
+ <span class="c1">// The asset is now downloaded from Usergrid and entity.asset == asset</span>
+<span class="p">})</span>
+</code></pre>
+<a href='#custom_usergridentity_subclasses' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='custom_usergridentity_subclasses'>Custom UsergridEntity Subclasses</h2>
+
+<p>Creating custom subclasses of the base <code>UsergridEntity</code> class (just like <code>UsergridUser</code> and <code>UsergridDevice</code>) is possible.</p>
<blockquote>
-<p>While it is possible to create mutliple instances of the <code>UsergridClient</code> class, we recomend using the shared instance where possible.</p>
+<p>For a working example of creating a custom subclass refer to the ActivityFeed sample app located in the <code>/Samples</code> folder. The custom subclass there is named <code>ActivityEntity</code>.</p>
</blockquote>
-<p>To initialize the shared instance of you will want to call the following code. This code usually goes best in the AppDelegate’s life cycle functions.</p>
+<ul>
+<li>To do so, subclass <code>UsergridEntity</code> and implement the required methods:</li>
+</ul>
<pre class="highlight swift"><code><span class="kd">import</span> <span class="kt">UsergridSDK</span>
-<span class="kd">func</span> <span class="nf">application</span><span class="p">(</span><span class="nv">application</span><span class="p">:</span> <span class="kt">UIApplication</span><span class="p">,</span> <span class="n">didFinishLaunchingWithOptions</span> <span class="nv">launchOptions</span><span class="p">:</span> <span class="p">[</span><span class="kt">NSObject</span><span class="p">:</span> <span class="kt">AnyObject</span><span class="p">]?)</span> <span class="o">-></span> <span class="kt">Bool</span>
- <span class="kt">Usergrid</span><span class="o">.</span><span class="nf">initSharedInstance</span><span class="p">(</span><span class="nv">orgID</span><span class="p">:</span> <span class="s">"orgID"</span><span class="p">,</span> <span class="nv">appID</span><span class="p">:</span> <span class="s">"appID"</span><span class="p">)</span>
- <span class="k">return</span> <span class="kc">true</span>
+<span class="kd">public</span> <span class="kd">class</span> <span class="kt">ActivityEntity</span><span class="p">:</span> <span class="kt">UsergridEntity</span> <span class="p">{</span>
+
+ <span class="kd">required</span> <span class="kd">public</span> <span class="nf">init</span><span class="p">(</span><span class="nv">type</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span><span class="p">?,</span> <span class="nv">propertyDict</span><span class="p">:</span> <span class="p">[</span><span class="kt">String</span> <span class="p">:</span> <span class="kt">AnyObject</span><span class="p">]?)</span> <span class="p">{</span>
+ <span class="k">super</span><span class="o">.</span><span class="nf">init</span><span class="p">(</span><span class="nv">type</span><span class="p">:</span> <span class="n">type</span><span class="p">,</span> <span class="nv">name</span><span class="p">:</span> <span class="n">name</span><span class="p">,</span> <span class="nv">propertyDict</span><span class="p">:</span> <span class="n">propertyDict</span><span class="p">)</span>
+ <span class="p">}</span>
+
+ <span class="kd">required</span> <span class="kd">public</span> <span class="nf">init</span><span class="p">?(</span><span class="n">coder</span> <span class="nv">aDecoder</span><span class="p">:</span> <span class="kt">NSCoder</span><span class="p">)</span> <span class="p">{</span>
+ <span class="k">super</span><span class="o">.</span><span class="nf">init</span><span class="p">(</span><span class="nv">coder</span><span class="p">:</span> <span class="n">aDecoder</span><span class="p">)</span>
+ <span class="p">}</span>
<span class="p">}</span>
</code></pre>
-<a href='#communication' class='anchor' aria-hidden=true><span class="header-anchor"></span></a><h2 id='communication'>Communication</h2>
<ul>
-<li>If you <strong>found a bug</strong>, open an issue.</li>
-<li>If you <strong>have a feature request</strong>, open an issue.</li>
-<li>If you <strong>want to contribute</strong>, submit a pull request.</li>
+<li>You will also need to register the custom subclass:</li>
</ul>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="nf">initSharedInstance</span><span class="p">(</span><span class="nv">orgId</span><span class="p">:</span> <span class="s">"orgId"</span><span class="p">,</span> <span class="nv">appId</span><span class="p">:</span> <span class="s">"appId"</span><span class="p">)</span>
+<span class="kt">UsergridEntity</span><span class="o">.</span><span class="nf">mapCustomType</span><span class="p">(</span><span class="s">"activity"</span><span class="p">,</span> <span class="nv">toSubclass</span><span class="p">:</span> <span class="kt">ActivityEntity</span><span class="o">.</span><span class="k">self</span><span class="p">)</span>
+</code></pre>
+
+<p>By registering your custom subclass, the <code>UsergridEntity</code> and <code>UsergridResponse</code> classes are able to generate instances of these classes based on the an entities <code>type</code>.</p>
+
+<p>In the above example, entities which have a <code>type</code> value of <code>activity</code> can now be cast as <code>ActivityEntity</code> objects. e.g.:</p>
+<pre class="highlight swift"><code><span class="kt">Usergrid</span><span class="o">.</span><span class="kt">GET</span><span class="p">(</span><span class="s">"activity"</span><span class="p">)</span> <span class="p">{</span> <span class="n">response</span> <span class="k">in</span>
+ <span class="k">var</span> <span class="nv">activityEntities</span><span class="p">:</span> <span class="p">[</span><span class="kt">ActivityEntity</span><span class="p">]?</span> <span class="o">=</span> <span class="n">response</span><span class="o">.</span><span class="n">entities</span> <span class="k">as?</span> <span class="p">[</span><span class="kt">ActivityEntity</span><span class="p">]</span>
+<span class="p">}</span>
+</code></pre>
</section>
</section>
<section id="footer">
- <p>© 2016 <a class="link" href="https://github.com/RobertWalsh/UsergridSDK" target="_blank" rel="external">Robert Walsh</a>. All rights reserved. (Last updated: 2016-02-08)</p>
+ <p>© 2016 <a class="link" href="https://github.com/apache/usergrid/tree/master/sdks/swift" target="_blank" rel="external">Robert Walsh</a>. All rights reserved. (Last updated: 2016-02-15)</p>
<p>Generated by <a class="link" href="https://github.com/realm/jazzy" target="_blank" rel="external">jazzy ♪♫ v0.5.0</a>, a <a class="link" href="http://realm.io" target="_blank" rel="external">Realm</a> project.</p>
</section>
</article>
http://git-wip-us.apache.org/repos/asf/usergrid/blob/c638c774/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/docSet.dsidx
----------------------------------------------------------------------
diff --git a/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/docSet.dsidx b/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/docSet.dsidx
index c17402a..8af0d38 100644
Binary files a/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/docSet.dsidx and b/sdks/swift/docs/docsets/UsergridSDK.docset/Contents/Resources/docSet.dsidx differ
http://git-wip-us.apache.org/repos/asf/usergrid/blob/c638c774/sdks/swift/docs/docsets/UsergridSDK.tgz
----------------------------------------------------------------------
diff --git a/sdks/swift/docs/docsets/UsergridSDK.tgz b/sdks/swift/docs/docsets/UsergridSDK.tgz
index a392d5c..464043b 100644
Binary files a/sdks/swift/docs/docsets/UsergridSDK.tgz and b/sdks/swift/docs/docsets/UsergridSDK.tgz differ