Merge branch 'new-docs' of git.int.sfo01.mml:mxml/api-spec into new-docs

Author: Bryan Berg

content/reference/authentication/flows/app-access-token.md

@@ -19,7 +19,23 @@ with URL-encoded POST body:
         &client_secret=[your client secret]
         &grant_type=client_credentials
 
-> Note: we also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the spec](http://tools.ietf.org/html/rfc6749#section-2.3.1).
+Example:
+
+<%= curl_example(:post, "access_token", :none, {
+    :subdomain => "account",
+    :path_prefix => "/oauth/",
+    :pretty_json => false,
+    :token => nil,
+    :content_type => nil,
+    :data => {
+        "grant_type" => "client_credentials",
+        "client_id" => "[your client_id]",
+        "client_secret" => "[your client secret]",
+    }
+}) %>
+
+
+> We also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the OAuth 2 spec](http://tools.ietf.org/html/rfc6749#section-2.3.1).
 
 App.net will respond with a JSON-encoded token:
 

content/reference/authentication/flows/password.md

@@ -49,9 +49,27 @@ Once you have been approved, using the password flow is pretty straightforward:
         &password=[user's password]
         &scope=[scopes separated by spaces]
 
-    > The use of `password_grant_secret` diverges from the OAuth 2.0 specificaion. `password_grant_secret` is a special token that we'll send you when your use of the password flow is approved.
-
-    > **You can require app-specific passwords** by providing a `require_app_specific_password=1` URL parameter. **[Two-Factor Auth users](http://blog.app.net/2013/03/13/added-security-for-your-app-net-account/) must use app-specific passwords** irrespective of this parameter. We strongly encourage the use of app-specific passwords by all users as they significantly increase account security.
+    Example:
+
+    <%= curl_example(:post, "access_token", :none, {
+        :subdomain => "account",
+        :path_prefix => "/oauth/",
+        :pretty_json => false,
+        :token => nil,
+        :content_type => nil,
+        :data => {
+            "grant_type" => "password",
+            "client_id" => "[your client_id]",
+            "password_grant_secret" => "[your password grant secret that was emailed to you]",
+            "username" => "[user's email address or username]",
+            "password" => "[user's password]",
+            "scope" => "[scopes separated by spaces]",
+        }
+    }) %>
+
+    > The use of `password_grant_secret` diverges from the OAuth 2.0 specification. `password_grant_secret` is a special token that we'll send you when your use of the password flow is approved.
+
+    > **You can require app-specific passwords** by providing a `require_app_specific_password=1` URL parameter. **[Two-Factor Auth users](http://blog.app.net/2013/03/13/added-security-for-your-app-net-account/) must use app-specific passwords** regardless of this parameter. We strongly encourage the use of app-specific passwords by all users as they significantly increase account security.
 
 1. If the authorization was successful, App.net will respond with a JSON-encoded token:
 

content/reference/authentication/flows/web.md

@@ -45,7 +45,24 @@ Your `redirect_uri` must be registered with App.net before you can use it.
         &redirect_uri=[your registered redirect URI]
         &code=[code received from redirect URI]
 
-    > Note: we also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the spec](http://tools.ietf.org/html/rfc6749#section-2.3.1).
+    Example:
+
+    <%= curl_example(:post, "access_token", :none, {
+        :subdomain => "account",
+        :path_prefix => "/oauth/",
+        :pretty_json => false,
+        :token => nil,
+        :content_type => nil,
+        :data => {
+            "grant_type" => "authorization_code",
+            "client_id" => "[your client_id]",
+            "client_secret" => "[your client secret]",
+            "redirect_uri" => "[your registered redirect URI]",
+            "code" => "[code received in the previous step]"
+        }
+    }) %>
+
+    > We also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the OAuth 2 spec](http://tools.ietf.org/html/rfc6749#section-2.3.1).
 
 1. App.net will respond with a JSON-encoded token: `{"access_token": "[user access token]", "token": {...Token object...}}`
 

content/reference/authentication/identity-delegation.md

@@ -45,6 +45,20 @@ Intentionally not addressed in this document are the following:
 
     > For App.net, the OAuth token endpoint is: `https://account.app.net/oauth/access_token`
 
+    Example:
+
+    <%= curl_example(:post, "access_token", :none, {
+        :subdomain => "account",
+        :path_prefix => "/oauth/",
+        :pretty_json => false,
+        :content_type => nil,
+        :data => {
+            "grant_type" => "delegate",
+            "delegate_client_id" => "[your client_id]",
+        }
+    }) %>
+
+
 1. The authorized client makes a request to the delegate client with two additional headers, `Identity-Delegate-Token` and `Identity-Delegate-Endpoint`:
 
         POST /protected/resource HTTP/1.1
@@ -60,7 +74,26 @@ Intentionally not addressed in this document are the following:
 
     > The delegate token and delegate endpoint may also be sent as delegate_token and delegate_endpoint in the query string or POST body.
 
-1. The delegate client identifies the resource server by using the `Identity-Delegate-Endpoint` header and makes a request to that endpoint with the Authorization header set.
+    Example:
+
+    <%= curl_example(:post, "protected/resource", :none, {
+        :subdomain => "delegate-client",
+        :domain => "example.com",
+        :path_prefix => "/",
+        :pretty_json => false,
+        :content_type => nil,
+        :token => nil,
+        :headers => {
+            "Identity-Delegate-Token" => "[delegate_token from previous step]",
+            "Identity-Delegate-Endpoint" => "https://alpha-api.app.net/stream/0/token",
+        },
+        :data => {
+            "do_some_stuff" => "1",
+            "fo_reals" => "1",
+        }
+    }) %>
+
+1. The delegate client identifies the resource server (App.net) by using the `Identity-Delegate-Endpoint` header and makes a request to that endpoint with the Authorization header set.
 
     > The query string parameters `delegate_token`, `client_id` and `client_secret` may be used in place of HTTP headers if desired.
 
@@ -100,12 +133,22 @@ Intentionally not addressed in this document are the following:
             }
         }
 
-    The resource server replies with an implementation-dependent description of the current user, which must include the client_id the authorized client. In the case of App.net, this is the Token object of the authorizing client's access_token as returned by the [Retrieve current Token](/reference/resources/token/#retrieve-current-token) endpoint.
+    App.net replies with information about the authorized delegate token. This is the Token object of the authorizing client's access_token as returned by the [Retrieve current Token](/reference/resources/token/#retrieve-current-token) endpoint.
 
     The delegate client may verify that the authorized client matches some external authentication scheme and/or list of authorized applications. If the delegate token is not valid for the delegate client's client_id, this call will return a `401 Unauthorized`.
 
     > For App.net, the identity delegation endpoint is: `https://alpha-api.app.net/stream/0/token`
 
+    Example:
+
+    <%= curl_example(:get, "token", :none, {
+        :pretty_json => false,
+        :headers => {
+            "Authorization" => "Basic [base64(client_id + ':' + client_secret)]",
+            "Identity-Delegate-Token" => "[delegate_token]",
+        },
+    }) %>
+
 ## Notes
 
 1. `delegate_token`s are valid as long as their associated `access_token`s are valid.

content/reference/authentication/index.md

@@ -133,11 +133,11 @@ When making a call to one of our API resources, there are three ways to include
 
 * Add `access_token` to query string
 
-    <%= curl_example(:get, "posts/1?access_token=<YOUR ACCESS TOKEN>", :none, {:data => "text=Test post", :content_type => nil, :token => nil}) %>
+    <%= curl_example(:get, "posts/1?access_token=<YOUR ACCESS TOKEN>", :none, {:data => {"text" => "Test post"}, :content_type => nil, :token => nil}) %>
 
 * Add `access_token` to HTTP body. 
 
-    > Note: this method will only work with the `PUT`, `POST`, and `PATCH` methods. `GET` and `DELETE` do not accept an HTTP body.
+    > This method will only work with the `PUT`, `POST`, and `PATCH` methods. `GET` and `DELETE` do not accept an HTTP body.
 
     <%= curl_example(:post, "posts", :none, {
         :data => {"text" => "Test post", "access_token" => "<YOUR ACCESS TOKEN>"},

content/reference/make-request/responses.md

@@ -9,7 +9,7 @@ title: "Responses"
 
 All responses to requests to the App.net API endpoints listed under [Resources](/reference/resources/), whether successful or not, will be returned in the same type of envelope structure. This document describes how that envelope works and what it may contain.
 
-*Please note: the [authentication endpoints](/reference/authentication) return a slightly different format that follows the OAuth2 specification.*
+*The [authentication endpoints](/reference/authentication) return a slightly different format that follows the OAuth2 specification.*
 
 ## Response Envelope
 
@@ -63,7 +63,7 @@ To request pretty-printing, send the following HTTP header with your request:
 
     X-ADN-Pretty-JSON: 1
 
-*Note: Sending any value is sufficient. Omit the header entirely if you wish to receive minified JSON.*
+Sending any value is sufficient. Omit the header entirely if you wish to receive minified JSON.
 
 ## Error Conditions
 

content/reference/meta/entities.md

@@ -13,7 +13,7 @@ Usually entities are extracted from the Post text by App.net's servers. We allow
 
 Ranges specified by entities may be adjacent, but may not overlap.
 
-<div class="alert alert-info"><b>Note:</b> <code>pos</code> and <code>len</code> fields are given as UTF-32 code points. Many string implementations (in particular, Cocoa's NSString class and Javascript's strings) use UTF-16 or UCS-2 encoding internally, and thus the indices given will not map directly to UTF-16 code points if encoded with surrogate pairs, e.g., emoji characters.</div>
+<div class="alert alert-info"><code>pos</code> and <code>len</code> fields are given as UTF-32 code points. Many string implementations (in particular, Cocoa's NSString class and Javascript's strings) use UTF-16 or UCS-2 encoding internally, and thus the indices given will not map directly to UTF-16 code points if encoded with surrogate pairs, e.g., emoji characters.</div>
 
 All of the following examples are about the following text:
 

content/reference/other/feeds.md

@@ -18,7 +18,7 @@ There are 2 different kinds of feeds, but they all follow the same pattern:
 
 We intend to support more feed formats and richer support for filters in the near future.
 
-*Note:* While the URLs are similar to other API URLs feeds, they are under a different root.
+While the URLs are similar to other API URLs feeds, they are under a different root.
 
 ## Filters
 

content/reference/other/web-intents.md

@@ -11,7 +11,7 @@ Web intents are an easy way to integrate with App.net; you don't even need to us
 
 
 <div class="alert alert-info alert-block">
-    <p><strong>Note:</strong> If you just want a simple follow or share button you can use <a href='http://app.net/about/buttons/'>button builder</a> instead. We've also open sourced the buttons so that you could host them your self. Checkout the <a href="https://github.com/appdotnet/piha">github repo</a> for more information on how to do that.</p>
+    <p>If you just want a simple follow or share button you can use <a href='http://app.net/about/buttons/'>button builder</a> instead. We've also open sourced the buttons so that you could host them your self. Checkout the <a href="https://github.com/appdotnet/piha">github repo</a> for more information on how to do that.</p>
 </div>
 
 ## The Post Intent

content/reference/resources/channel/search.md

@@ -11,7 +11,9 @@ title: "Channel Search"
 
 Returns [Channel](/reference/resources/channel/) objects which match a given search query. Because channels have no inherent notion of description or name, we take textual data from common channel annotations which contain such fields, e.g. <code>net.patter-app.settings</code>. We also allow filtering on specific channel properties, such as channel type. No matter what query data is supplied, the search results will respect channel ACLs, and results are limited to non-private channels if the requesting access token does not have the <code>messages</code> scope.
 
-<%= general_params_note_for "channel" %> Note: Pagination works for all orderings on this endpoint. Be sure to make requests with before_id=min_id or since_id=max_id as usual when paginating the popularity-sorted results. Separate lists of terms by spaces.
+Separate lists of terms by spaces.
+
+<%= general_params_note_for "channel" %>
 
 <%= endpoint "GET", "channels/search", "User", "public_messages</code> or <code>messages" %>