Permalink
Browse files

Documenting JSONP and endpoints that don't require auth

  • Loading branch information...
1 parent d4c6c69 commit 06f0ab527ff4b75ade8ae4c1fe1fbef8808ebc64 @voidfiles voidfiles committed with berg Sep 12, 2012
Showing with 53 additions and 3 deletions.
  1. +5 −0 migrations.md
  2. +2 −2 objects.md
  3. +26 −1 resources/README.md
  4. +20 −0 responses.md
View
@@ -20,6 +20,11 @@ would disable [response envelopes](#current-migrations) for that particular call
### Migration Response Header
All calls to our endpoints will return X-ADN-Migrations-Enabled, a query-string encoded list of migration keys that are enabled for that particular API call. This list will take into account globally toggled migrations as well as those enabled by X-ADN-Migration-Overrides.
+### Using Migrations with JSONP
+For JSONP requests we offer the ability to override the default migration behavior on a per-call basis. To do this, add a list of valid [migration keys](#current-migrations) and values (0 or 1) to the query string. For example, `https://alpha-api.app.net/stream/0/posts/stream/global?callback=json_callback&response_envelope=0`
+
+**Toggling migrations with the query string is ONLY for availble JSONP requests.** Use the header mechanism for all other requests.
+
## Current Migrations
<table>
View
@@ -380,12 +380,12 @@ A Post is the other central object utilized by the App.net Stream API. It has ri
<tr>
<td><code>you_starred</code></td>
<td>boolean</td>
- <td>Have you starred this Post?</td>
+ <td>Have you starred this Post? May be omitted if this is not an authenticated request.</td>
</tr>
<tr>
<td><code>starred_by</code></td>
<td>list</td>
- <td>A partial list of users who have starred this post. This is not comprehensive and is meant to be a sample of users who have starred this post giving preference to users the current user follows. This is only included if ```include_starred_by=1``` is passed to App.net.</td>
+ <td>A partial list of users who have starred this post. This is not comprehensive and is meant to be a sample of users who have starred this post giving preference to users the current user follows. This is only included if <code>include_starred_by=1</code> is passed to App.net. May be omitted if this is not an authenticated request.</td>
</tr>
</table>
View
@@ -3,7 +3,7 @@ The App.net Stream API is a JSON API.
Guiding principles are:
-* Always return JSON.
+* Always return JSON. If you are using JSONP, the returned JSON will be wrapped in a function call.
* Utilize HTTP error codes and methods.
* In general, required parameters are in URLs; optional parameters are specified in the query string. **This is not always the case.**
* If we need complex data structures from you, you should send them as a JSON string. We don't need any more conventions for putting arrays and dictionaries directly into URL-encoded GET/POST values.
@@ -18,53 +18,63 @@ Please use https://alpha-api.app.net/ to access the APIs.
<tr>
<th>Path</th>
<th>HTTP Method</th>
+ <th>Authentication Required?</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>/stream/0/users/[user_id]</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#retrieve-a-user">Retrieve a User</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/follow</td>
<td>POST</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#follow-a-user">Follow a User</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/follow</td>
<td>DELETE</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#unfollow-a-user">Unfollow a User</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/following</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#list-users-a-user-is-following">List users a User is following</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/followers</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#list-users-following-a-user">List users following a User</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/mute</td>
<td>POST</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#mute-a-user">Mute a User</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/mute</td>
<td>DELETE</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#unmute-a-user">Unmute a User</a></td>
</tr>
<tr>
<td>/stream/0/users/me/muted</td>
<td>GET</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#list-muted-users">List muted users</a></td>
</tr>
<tr>
<td>/stream/0/posts/[post_id]/stars</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#list-users-who-have-starred-a-post">List Users who have starred a Post</a></td>
</tr>
</tbody>
@@ -76,13 +86,15 @@ Please use https://alpha-api.app.net/ to access the APIs.
<tr>
<th>Path</th>
<th>HTTP Method</th>
+ <th>Authentication Required?</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>/stream/0/token</td>
<td>GET</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/token.md#retrieve-current-token">Check current Token</a></td>
</tr>
</tbody>
@@ -95,68 +107,81 @@ Please use https://alpha-api.app.net/ to access the APIs.
<tr>
<th>Path</th>
<th>HTTP Method</th>
+ <th>Authentication Required?</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>/stream/0/posts</td>
<td>POST</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#create-a-post">Create a Post</a></td>
</tr>
<tr>
<td>/stream/0/posts/[post_id]</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-a-post">Retrieve a Post</a></td>
</tr>
<tr>
<td>/stream/0/posts/[post_id]</td>
<td>DELETE</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#delete-a-post">Delete a Post</a></td>
</tr>
<tr>
<td>/stream/0/posts/[post_id]/replies</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-the-replies-to-a-post">Retrieve the replies to a Post</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/posts</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-posts-created-by-a-user">Retrieve Posts created by a User</a></td>
</tr>
<tr>
<td>/stream/0/posts/[post_id]/star</td>
<td>POST</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#star-a-post">Star a Post</a></td>
</tr>
<tr>
<td>/stream/0/posts/[post_id]/star</td>
<td>DELETE</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#unstar-a-post">Unstar a Post</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/stars</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-posts-starred-by-a-user">Retrieve Posts starred by a User</a></td>
</tr>
<tr>
<td>/stream/0/users/[user_id]/mentions</td>
<td>GET</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-posts-mentioning-a-user">Retrieve Posts mentioning a User</a></td>
</tr>
<tr>
<td>/stream/0/posts/stream</td>
<td>GET</td>
+ <td>Yes</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-a-users-personalized-stream">Retrieve a User's personalized stream</a></td>
</tr>
<tr>
<td>/stream/0/posts/stream/global</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-the-global-stream">Retrieve the Global stream</a></td>
</tr>
<tr>
<td>/stream/0/posts/tag/[hashtag]</td>
<td>GET</td>
+ <td>No</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-tagged-posts">Retrieve tagged Posts</a></td>
</tr>
</tbody>
View
@@ -10,6 +10,26 @@ The top-level response is an object containing two keys. The first key, ```data`
The second key present, ```meta```, corresponds to an object containing additional information about the request. This object will always contain ```code```, a copy of the HTTP status code that has been returned. It will also contain pagination data, when relevant.
+## JSONP
+
+We support JSONP for easy, unauthenticated cross-domain API requests with wide browser support. Normal JSON responses are wrapped in a Javascript function so they may be included in a webpage and fetched directly by the browser via a `script` tag. It is not possible to make requests to API endpoints which require authentication with JSONP.
+
+To use JSONP, add a `callback` parameter to the request's query string. For example:
+
+ https://alpha-api.app.net/stream/0/posts/stream/global?callback=awesome
+
+Will result in a response that looks something like this:
+
+ awesome({...})
+
+When using JSONP, our servers will return a 200 status code in the HTTP response, regardless of the effective status code.
+
+For more information on JSONP, see the Wikipedia page for [JSONP](http://en.wikipedia.org/wiki/JSONP).
+
+## CORS
+
+We support CORS for authenticated cross-domain API requests direct from browsers. Support for CORS may vary by browser. When using CORS, you are still responsible for obtaining, storing and supplying a valid access token with each request, if access to authenticated endpoints is required. For more information on CORS, see the Wikipedia page for [CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing).
+
### Error Conditions
If the request was unsuccessful for some reason, no ```data``` key will be returned -- the reponse object will only contain a ```meta``` object. Additional information pertaining to the type of error generated will be returned inside the ```meta``` object. In particular, the ```code``` and ```error_message``` keys will point out what sort of error occurred. There may also be a uniquely-identifying ```error_slug``` present that can be used to get more information about the error and which may be helpful in support requests with App.net staff.

0 comments on commit 06f0ab5

Please sign in to comment.