From c43d23b838080d80519fca8abdf964a7e96e06b7 Mon Sep 17 00:00:00 2001 From: Ben Cochran Date: Sun, 3 Mar 2013 04:42:50 -0800 Subject: [PATCH 001/231] =?UTF-8?q?Fix=20incorrect=20=E2=80=9Cthey?= =?UTF-8?q?=E2=80=99re=E2=80=9D=20vs.=20=E2=80=9Ctheir=E2=80=9D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- content/docs/basics/messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/basics/messaging.md b/content/docs/basics/messaging.md index f8ebfc0..92ffdeb 100644 --- a/content/docs/basics/messaging.md +++ b/content/docs/basics/messaging.md @@ -19,7 +19,7 @@ When you create a Channel, you decide who can read and write to that channel. Th * Create a private group chat between multiple App.net users * Create a moderated group that can be read by a set of users and written to by a different set of users -* Create a chat room where App.net users can read and write messages while their in the room and leave whenever they want +* Create a chat room where App.net users can read and write messages while they're in the room and leave whenever they want If a user is authorized to read a Channel, they can also subscribe to a channel. This allows you to keep track of channels an messages at a more granular level. From 3a24c6f38cd165018c4616243afbb30e478265dd Mon Sep 17 00:00:00 2001 From: Luis Abreu Date: Wed, 6 Mar 2013 10:40:47 +0000 Subject: [PATCH 002/231] s/The includes/This includes Your friendly neighborhood spellchecker. --- content/docs/resources/file/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/file/index.md b/content/docs/resources/file/index.md index 15d75c4..4e1f622 100644 --- a/content/docs/resources/file/index.md +++ b/content/docs/resources/file/index.md @@ -295,7 +295,7 @@ The current valid formats: * `metadata`: This includes the entire File resource except for the `annotations`, `source`, and `user` fields. * `oembed`: This includes any oembed data we can generate for this file. This could be empty. This format can only be used with the `net.app.core.oembed` annotation. -* `url`: The includes just a url pointing to this file's contents. +* `url`: This includes just a url pointing to this file's contents. Please see the [File replacement annotation value](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file.md) for more details and examples. From bdff348449a1bf6aaa0283d627dfe9718fae98a5 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Thu, 14 Mar 2013 10:27:05 -0700 Subject: [PATCH 003/231] Add link to My Apps --- layouts/default.html | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/layouts/default.html b/layouts/default.html index 11e47ca..f0b4071 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -42,6 +42,7 @@
  • External Resources
    • - - - - - From 9e62d8c42b1572ac7901b53470b6871dbaca82ef Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Thu, 14 Mar 2013 15:57:58 -0700 Subject: [PATCH 004/231] Replace alpha references --- content/docs/authentication/flows/password.md | 2 +- content/docs/authentication/identity-delegation.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/authentication/flows/password.md b/content/docs/authentication/flows/password.md index 088b224..8d4204a 100644 --- a/content/docs/authentication/flows/password.md +++ b/content/docs/authentication/flows/password.md @@ -38,7 +38,7 @@ Once approved, it's pretty straightforward: 1. From your client, make a request to the token endpoint: - POST https://alpha.app.net/oauth/access_token + POST https://account.app.net/oauth/access_token with URL-encoded POST body: diff --git a/content/docs/authentication/identity-delegation.md b/content/docs/authentication/identity-delegation.md index 290aa27..9668e16 100644 --- a/content/docs/authentication/identity-delegation.md +++ b/content/docs/authentication/identity-delegation.md @@ -32,7 +32,7 @@ Intentionally not addressed in this document are the following: 1. The authorized client makes an authenticated POST request to the resource server OAuth token endpoint: POST /oauth/access_token HTTP/1.1 - Host: alpha.app.net + Host: account.app.net Authorization: Bearer [access_token] Content-Length: 59 Content-Type: application/x-www-form-urlencoded @@ -43,7 +43,7 @@ Intentionally not addressed in this document are the following: {"delegate_token": "[delegate token]"} - > For App.net, the OAuth token endpoint is: `https://alpha.app.net/oauth/access_token` + > For App.net, the OAuth token endpoint is: `https://account.app.net/oauth/access_token` 1. The authorized client makes a request to the delegate client with two additional headers, `Identity-Delegate-Token` and `Identity-Delegate-Endpoint`: From ee39958ef37160bb27ac3f51304031880be21719 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Thu, 14 Mar 2013 17:05:57 -0700 Subject: [PATCH 005/231] Clean up --- content/docs/authentication/flows/password.md | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/content/docs/authentication/flows/password.md b/content/docs/authentication/flows/password.md index 8d4204a..cfced5f 100644 --- a/content/docs/authentication/flows/password.md +++ b/content/docs/authentication/flows/password.md @@ -7,34 +7,34 @@ title: "Password Flow" * TOC {:toc} -This is referred to as the Resource Owner Password Credential flow in the OAuth 2.0 spec. However, in order to protect the integrity of `client_secret`s, we require the use of a separate token to be included with flows. - This flow is useful for obtaining an access token authorized for specific scopes when pushing the user into a browser-based flow is impractical for technical or user-experience reasons. -## Important notes +This is referred to as the Resource Owner Password Credential flow in the OAuth 2.0 spec. However, in order to protect the integrity of `client_secret`s, we require the use of a separate token to be included with flows. -**Security of user accounts is the most important thing.** When in doubt, err on the side of securing user password information, rather than optimizing for user experience. +## Obtaining approval to use the password flow -**Your application must be specifically approved to use this flow.** To obtain authorization, please email password-auth@app.net from your user account's email address and include your application's `client_id`, your username, and an explanation of your situation. +**Your application must be specifically approved to use this flow.** To obtain authorization, please email [password-auth@app.net](mailto:password-auth@app.net) from the email address associated with your developer account and include your application's `client_id`, your username, and an explanation of your situation (e.g. "I am building a native app for iOS"). -**You may require app-specific passwords with the `require_app_specific_password=1` URL parameter.** Two-Factor Auth users must use app-specific passwords irrespective of this parameter. We strongly encourage the use of app-specific passwords to all users as they significantly increase account security. +## Rules -## Additional rules +**Security of user accounts is the most important thing.** When in doubt, err on the side of securing user password information, rather than optimizing for user experience. > Some of these rules might limit what you can do with your app. Please do not attempt to circumvent them, or we will disable your application token. That may sound harsh, but it is of utmost importance that we protect the integrity of the service and the security of user accounts. +> These flows should only be used in cases where browser-based authentication is impractical. For one-off applications, shell scripts, etc., please generate an access token for your app via [My Apps](https://account.app.net/developer/apps/). + 1. **NEVER** store user password information, no matter how securely. Users should be able to disable access to your application at any time by revoking authorization. Access tokens are designed not to expire unless users take explicit action, so there is no need to build in a mechanism to reauthenticate that would require storing passwords. -1. Do not send user password information over the network, except to the prescribed App.net OAuth endpoint. +1. **NEVER** send user password information over the network, except to the prescribed App.net OAuth endpoint. 1. **NEVER** log user password information, even debug logging to your app or device's console. It is too easy to accidentally leak password information this way. -1. These flows should only be used in cases where browser-based authentication is impractical. For one-off applications, shell scripts, please use the pre-generated access token available in the "Apps" section of App.net. -1. Users must have a way to see which scopes are being requested by an application. This can be behind a "more info" button, but must at least be exposed on the login screen, before users are required to enter their password information to coninue. -1. By default, **users will receive an email each time they authorize an application with this flow**, listing the name of the application, the scopes requested and the time that authorization was performed. -1. If an error is returned from the OAuth endpoint, it MUST be displayed to users verbatim. +1. Users **MUST** have a way to see which scopes are being requested by an application. This can be behind a "more info" button, but must at least be exposed on the login screen, before users are required to enter their password information to continue. +1. If an error is returned from the OAuth endpoint, it **MUST** be displayed to users verbatim. 1. If these rules are updated, application developers must make reasonable attempts to comply with new regulations wherever possible. ## Procedure -Once approved, it's pretty straightforward: +> By default **users will receive an email each time they authorize an application with this flow** listing the name of the application, the scopes requested and the time that authorization was performed. + +Once you have been approved, using the password flow is pretty straightforward: 1. From your client, make a request to the token endpoint: @@ -49,7 +49,9 @@ Once approved, it's pretty straightforward: &password=[user's password] &scope=[scopes separated by spaces] - > Note: 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. + > 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. 1. If the authorization was successful, App.net will respond with a JSON-encoded token: From 53ddc28c35b6cd439cd62e677304b6e1982c04ba Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Fri, 15 Mar 2013 15:48:49 -0700 Subject: [PATCH 006/231] Add file storage limitations --- content/docs/resources/file/content.md | 12 +----------- content/docs/resources/file/index.md | 4 ++++ content/docs/resources/file/lifecycle.md | 2 +- 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/content/docs/resources/file/content.md b/content/docs/resources/file/content.md index 4fcc78d..bd32495 100644 --- a/content/docs/resources/file/content.md +++ b/content/docs/resources/file/content.md @@ -40,21 +40,11 @@ This endpoint will return a 302 Redirect to a temporary URL for the content of t -### Example - -> PUT https://alpha-api.app.net/stream/0/files/1/content -> -> Content-Type: image/jpeg -> -> DATA [raw file, not base64 encoded] -> -> 204 No Content - ## Set File content Set the content for an incomplete File. The content type for this request must be the content type of the file you are uploading. -This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. +This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/docs/resources/file/#limits). <%= migration_warning ['response_envelope'] %> diff --git a/content/docs/resources/file/index.md b/content/docs/resources/file/index.md index 15d75c4..5f5f6b2 100644 --- a/content/docs/resources/file/index.md +++ b/content/docs/resources/file/index.md @@ -194,6 +194,10 @@ Write tokens are NEVER returned in annotations. The streaming API does not inclu In general, file content is made available to other users by referencing it in annotations on other App.net objects, e.g., posts and messages. However, it is also possible to explicitly mark a file as public, which will allow to to be referenced publicly without being attached to another object. You can do this by setting the `public` value to `true` on a file at creation time (or after the fact). Upon doing this, the file will be populated with a `url_permanent` field which will contain a link to the file's content. This link will remain active until the file is no longer set to public. +## Limits + +Paid tier accounts receive 10GB total storage, with a 100MB maximum individual file size. Free tier accounts receive 500MB total storage, with a 10MB maximum individual file size. Individual accounts may have earned additional file storage through the invitation system (see this [blog post](http://blog.app.net/2013/02/25/introducing-a-free-tier/)). To determine the used and available space for an individual user, inspect the `storage` field of their [user token](/docs/resources/token/#retrieve-current-token). + ## General Parameters Requests that return streams of Files respond to [pagination parameters](/docs/basics/pagination). Additionally they accept the following query string parameters: diff --git a/content/docs/resources/file/lifecycle.md b/content/docs/resources/file/lifecycle.md index e48f610..1e7a9e2 100644 --- a/content/docs/resources/file/lifecycle.md +++ b/content/docs/resources/file/lifecycle.md @@ -15,7 +15,7 @@ An App.net File object can be created without setting the file content. This is You can also create a complete File object with one request by including the file content with the File metadata. To create a complete file object, send a POST with an HTTP header of `Content-Type: multipart/form-data`. Our API expects one part of the request body to contain a `Content-Disposition` header with a value for `filename` and `name="content"`. The data from this part will be used as the file's content. If you wish to send your data as Base64 encoded instead of as a byte stream you must include a `Content-Transfer-Encoding: base64` header. If there is a part with `name="metadata"` and `Content-Type: application/json` then we will parse that JSON as the file's metadata. Otherwise, we will construct the metadata from the `form-data` sent in the request body. -When creating a complete file, this endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. +When creating a complete file, this endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/docs/resources/file/#limits). <%= migration_warning ['response_envelope'] %> From 6e2b96800fb54463e56db672d7876a3c1c62dd90 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Fri, 15 Mar 2013 16:55:06 -0700 Subject: [PATCH 007/231] Add missing endpoints --- content/docs/resources/index.md | 8 +++++++ layouts/partials/endpoints/explore-stream.md | 24 ++++++++++++++++++++ 2 files changed, 32 insertions(+) create mode 100644 layouts/partials/endpoints/explore-stream.md diff --git a/content/docs/resources/index.md b/content/docs/resources/index.md index 1293bfd..0401815 100644 --- a/content/docs/resources/index.md +++ b/content/docs/resources/index.md @@ -36,6 +36,10 @@ Please use https://alpha-api.app.net/ to access the APIs. <%= render 'partials/endpoints/message' %> +## File + +<%= render 'partials/endpoints/filter' %> + ## Stream <%= render 'partials/endpoints/stream' %> @@ -63,3 +67,7 @@ Please use https://alpha-api.app.net/ to access the APIs. ## Place <%= render 'partials/endpoints/place' %> + +## Explore Stream + +<%= render 'partials/endpoints/explore-stream' %> diff --git a/layouts/partials/endpoints/explore-stream.md b/layouts/partials/endpoints/explore-stream.md new file mode 100644 index 0000000..9400eeb --- /dev/null +++ b/layouts/partials/endpoints/explore-stream.md @@ -0,0 +1,24 @@ + + + + + + + + + + + + + + + + + + + + + + + +
    DescriptionMethodPathToken
    Retrieve all Explore StreamsGET/stream/0/posts/stream/exploreNone
    Retrieve an Explore StreamGET/stream/0/posts/stream/explore/[slug]None
    \ No newline at end of file From e50d1281f2ef9367da064ba3d14aeb7f378aff68 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Tue, 19 Mar 2013 13:43:51 -0700 Subject: [PATCH 008/231] Add user blocking to docs --- content/docs/resources/user/blocking.md | 332 ++++++++++++++++++++++++ content/docs/resources/user/index.md | 8 +- layouts/default.html | 1 + layouts/partials/endpoints/user.md | 26 +- 4 files changed, 365 insertions(+), 2 deletions(-) create mode 100644 content/docs/resources/user/blocking.md diff --git a/content/docs/resources/user/blocking.md b/content/docs/resources/user/blocking.md new file mode 100644 index 0000000..4032d7c --- /dev/null +++ b/content/docs/resources/user/blocking.md @@ -0,0 +1,332 @@ +--- +title: "User Blocking" +--- + +# Blocking + +* TOC +{:toc} + +## Block a User + +Block a user from seeing your App.net content. This means the user will not be able to see, star, reply to, or repost your content. This user will also effectively be muted for you. This will automatically unfollow both users from each other. + +In most cases, [muting a user](/docs/resources/user/muting/#mute-a-user) is probably sufficient since that hides all of a user's content from you. If a user is aggressively reposting or starring your content, blocking them will prevent them from interacting with your content at all. + +<%= migration_warning ['response_envelope'] %> + +<%= endpoint "POST", "users/[user_id]/block", "User", "follow" %> + +### Data + + + + + + + + + + + + + + + + + + +
    NameRequired?TypeDescription
    user_idRequiredstringThe id of the User to block. You can also specify @username as a user_id.
    + +### Example + +> POST https://alpha-api.app.net/stream/0/users/1/block + +~~~ js +{ + "data": { + "id": "1", // note this is a string + "username": "mthurman", + "name": "Mark Thurman", + "description": { + "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "entities": { + "mentions": [{ + "name": "appdotnet", + "id": "3", + "pos": 52, + "len": 10 + }], + "hashtags": [{ + "name": "api", + "pos": 70, + "len": 4 + }], + "links": [{ + "text": "teaching you", + "url": "https://github.com/appdotnet/api-spec", + "pos": 29, + "len": 12 + }] + } + }, + "timezone": "US/Pacific", + "locale": "en_US", + "avatar_image": { + "height": 512, + "width": 512, + "url": "https://example.com/avatar_image.jpg", + "is_default": false + }, + "cover_image": { + "height": 118, + "width": 320, + "url": "https://example.com/cover_image.jpg", + "is_default": false + }, + "type": "human", + "created_at": "2012-07-16T17:23:34Z", + "counts": { + "following": 100, + "followers": 200, + "posts": 24, + "stars": 76 + }, + "follows_you": false, + "you_blocked": true, + "you_follow": false, + "you_muted": false + }, + "meta": { + "code": 200 + } +} +~~~ + +## Unblock a User + +Allow a blocked user to interact with my content. + +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* + +<%= migration_warning ['response_envelope'] %> + +<%= endpoint "DELETE", "users/[user_id]/block", "User", "follow" %> + +### Parameters + + + + + + + + + + + + + + + + + + +
    NameRequired?TypeDescription
    user_idRequiredstringThe id of the User to unblock. You can also specify @username as a user_id.
    + +### Example + +> DELETE https://alpha-api.app.net/stream/0/users/1/block + +~~~ js +{ + "data": { + "id": "1", // note this is a string + "username": "mthurman", + "name": "Mark Thurman", + "description": { + "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "entities": { + "mentions": [{ + "name": "appdotnet", + "id": "3", + "pos": 52, + "len": 10 + }], + "hashtags": [{ + "name": "api", + "pos": 70, + "len": 4 + }], + "links": [{ + "text": "teaching you", + "url": "https://github.com/appdotnet/api-spec", + "pos": 29, + "len": 12 + }] + } + }, + "timezone": "US/Pacific", + "locale": "en_US", + "avatar_image": { + "height": 512, + "width": 512, + "url": "https://example.com/avatar_image.jpg", + "is_default": false + }, + "cover_image": { + "height": 118, + "width": 320, + "url": "https://example.com/cover_image.jpg", + "is_default": false + }, + "type": "human", + "created_at": "2012-07-16T17:23:34Z", + "counts": { + "following": 100, + "followers": 200, + "posts": 24, + "stars": 76 + }, + "follows_you": false, + "you_blocked": false, + "you_follow": false, + "you_muted": false, + }, + "meta": { + "code": 200 + } +} +~~~ + +## List blocked Users + +Retrieve a list of blocked users. If you have a [user token](/docs/authentication/#access-tokens) you can request blocked users for the current user by using `me` as the requested user id. If you have an [app token](/docs/authentication/#access-tokens) you can request blocked users for any user that has authorized your app. + +<%= migration_warning ['response_envelope'] %> + +<%= endpoint "GET", "users/[user_id]/blocked", "Any" %> + +### Parameters + +None. + +### Example + +> GET https://alpha-api.app.net/stream/0/users/me/blocked + +~~~ js +{ + "data": [ + { + "id": "1", // note this is a string + "username": "mthurman", + "name": "Mark Thurman", + "description": { + "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "entities": { + "mentions": [{ + "name": "appdotnet", + "id": "3", + "pos": 52, + "len": 10 + }], + "hashtags": [{ + "name": "api", + "pos": 70, + "len": 4 + }], + "links": [{ + "text": "teaching you", + "url": "https://github.com/appdotnet/api-spec", + "pos": 29, + "len": 12 + }] + } + }, + "timezone": "US/Pacific", + "locale": "en_US", + "avatar_image": { + "height": 512, + "width": 512, + "url": "https://example.com/avatar_image.jpg", + "is_default": false + }, + "cover_image": { + "height": 118, + "width": 320, + "url": "https://example.com/cover_image.jpg", + "is_default": false + }, + "type": "human", + "created_at": "2012-07-16T17:23:34Z", + "counts": { + "following": 100, + "followers": 200, + "posts": 24, + "stars": 76 + }, + "follows_you": false, + "you_blocked": true, + "you_follow": false, + "you_muted": false, + }, + ... + ], + "meta": { + "code": 200 + } +} +~~~ + + +## Retrieve blocked User IDs for multiple Users + +Returns a list of blocked User ids for each User id requested. At most 200 User ids can be requested. + +<%= migration_warning ['response_envelope'] %> + +<%= endpoint "GET", "users/blocked/ids", "App" %> + +### Parameters + + + + + + + + + + + + + + + + + + +
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of User ids to retrieve blocked User ids for
    + +### Example + +> GET https://alpha-api.app.net/stream/0/users/blocked/ids?ids=1,2 + +~~~ js +{ + "data": { + "1": [ + "3", + "29" + ], + "2": [] + }, + "meta": { + "code": 200 + } +} +~~~ \ No newline at end of file diff --git a/content/docs/resources/user/index.md b/content/docs/resources/user/index.md index c4f3735..4325d56 100644 --- a/content/docs/resources/user/index.md +++ b/content/docs/resources/user/index.md @@ -64,6 +64,7 @@ A User is the central object of the App.net APIs. User objects have usernames, f "stars": 76 }, "follows_you": false, + "you_blocked": false, "you_follow": true, "you_muted": false, "you_can_subscribe": true, @@ -199,6 +200,11 @@ A User is the central object of the App.net APIs. User objects have usernames, f boolean Does this user follow the user making the request? May be omitted if this is not an authenticated request. + + you_blocked + boolean + Has the user making the request blocked this user? May be omitted if this is not an authenticated request. + you_follow boolean @@ -207,7 +213,7 @@ A User is the central object of the App.net APIs. User objects have usernames, f you_muted boolean - Has the user making the request blocked this user? May be omitted if this is not an authenticated request. + Has the user making the request muted this user? May be omitted if this is not an authenticated request. you_can_subscribe diff --git a/layouts/default.html b/layouts/default.html index de54bdb..619e9a0 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -66,6 +66,7 @@
  • Profile
  • Following
  • Muting
    • +
  • Blocking
  • Post Interactions
  • Post
    • diff --git a/layouts/partials/endpoints/user.md b/layouts/partials/endpoints/user.md index 60a066f..4fd7c0b 100644 --- a/layouts/partials/endpoints/user.md +++ b/layouts/partials/endpoints/user.md @@ -68,6 +68,18 @@ /stream/0/users/[user_id]/mute User + + Block a User + POST + /stream/0/users/[user_id]/block + User + + + Unblock a User + DELETE + /stream/0/users/[user_id]/block + User + Retrieve multiple Users GET @@ -108,7 +120,7 @@ Retrieve muted Users GET /stream/0/users/[user_id]/muted - User + Any Retrieve muted User IDs for multiple Users @@ -116,6 +128,18 @@ /stream/0/users/muted/ids App + + Retrieve blocked Users + GET + /stream/0/users/[user_id]/blocked + Any + + + Retrieve blocked User IDs for multiple Users + GET + /stream/0/users/blocked/ids + App + Retrieve Users who reposted a Post GET From 4a4767901af0c07f1a9f5b7a600297eb94504b24 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Wed, 20 Mar 2013 17:21:18 -0700 Subject: [PATCH 009/231] Clarify endpoints/parameters, clean up --- content/docs/resources/channel/lifecycle.md | 33 +--- content/docs/resources/channel/lookup.md | 63 ++----- content/docs/resources/channel/muting.md | 62 ++----- .../docs/resources/channel/subscriptions.md | 151 ++++------------ content/docs/resources/explore/index.md | 31 +--- content/docs/resources/file/content.md | 50 +----- content/docs/resources/file/lifecycle.md | 60 ++----- content/docs/resources/file/lookup.md | 62 ++----- content/docs/resources/filter/lifecycle.md | 97 ++--------- content/docs/resources/interaction/index.md | 6 +- content/docs/resources/message/lifecycle.md | 90 ++-------- content/docs/resources/message/lookup.md | 68 ++------ content/docs/resources/place/index.md | 95 +++------- content/docs/resources/post/lifecycle.md | 69 ++------ content/docs/resources/post/lookup.md | 55 ++---- content/docs/resources/post/replies.md | 27 +-- content/docs/resources/post/report.md | 25 +-- content/docs/resources/post/reposts.md | 54 ++---- content/docs/resources/post/stars.md | 75 ++------ content/docs/resources/post/streams.md | 66 ++----- content/docs/resources/stream-marker/index.md | 6 +- content/docs/resources/stream/lifecycle.md | 118 +++---------- .../docs/resources/text-processor/index.md | 25 +-- content/docs/resources/token/index.md | 20 +-- content/docs/resources/user/following.md | 162 ++++-------------- content/docs/resources/user/lookup.md | 81 ++------- content/docs/resources/user/muting.md | 92 +++------- .../docs/resources/user/post-interactions.md | 54 ++---- content/docs/resources/user/profile.md | 56 +----- layouts/partials/endpoint.md | 8 +- layouts/partials/parameters-typed.md | 20 +++ layouts/partials/parameters.md | 18 ++ lib/helpers.rb | 21 ++- 33 files changed, 427 insertions(+), 1493 deletions(-) create mode 100644 layouts/partials/parameters-typed.md create mode 100644 layouts/partials/parameters.md diff --git a/content/docs/resources/channel/lifecycle.md b/content/docs/resources/channel/lifecycle.md index a7a9d1a..6a2f2b1 100644 --- a/content/docs/resources/channel/lifecycle.md +++ b/content/docs/resources/channel/lifecycle.md @@ -21,11 +21,7 @@ Send a JSON document that matches the [Channel schema](/docs/resources/channel/) <%= endpoint "POST", "channels", "User", "public_messages or messages"%> -### Data - -None. - -### Example +#### Example > POST https://alpha-api.app.net/stream/0/channels > @@ -81,28 +77,11 @@ If you want to add or update a Channel's annotations, you may include the option <%= endpoint "PUT", "channels/[channel_id]", "User", "public_messages or messages"%> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel to update
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel to update."] +]%> + +#### Example > PUT https://alpha-api.app.net/stream/0/channels/1 > diff --git a/content/docs/resources/channel/lookup.md b/content/docs/resources/channel/lookup.md index d6273e6..aafddab 100644 --- a/content/docs/resources/channel/lookup.md +++ b/content/docs/resources/channel/lookup.md @@ -15,28 +15,11 @@ Returns a specific [Channel](/docs/resources/channel/). <%= endpoint "GET", "channels/[channel_id]", "User", "public_messages     or messages"%> -### Parameters +<%= url_params [ + ["channel_id", "The id of the Channel to retrieve."] +]%> - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredstringThe channel id
    - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/channels/2 @@ -85,28 +68,11 @@ Returns multiple Channels requested by id. At most 200 channels can be requested <%= endpoint "GET", "channels", "User", "public_messages     or messages"%> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of Channel ids to retrieve.
    +<%= query_params [ + ["ids", "A comma separated list of ids of Channels to retrieve."] +]%> -### Example +#### Example > GET https://alpha-api.app.net/stream/0/channels?ids=1,2,6502 @@ -188,11 +154,7 @@ Returns a stream of all Channels the current user has created. This endpoint res <%= endpoint "GET", "users/me/channels", "User", "public_messages     or messages"%> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/channels @@ -240,7 +202,6 @@ None. } ~~~ - ## Retrieve number of unread PM Channels Returns the current number of `net.app.core.pm` Channels where `has_unread: true` for the current user. @@ -248,11 +209,7 @@ Returns the current number of `net.app.core.pm` Channels where `has_unread: true <%= endpoint "GET", "users/me/channels/pm/num_unread", "User", "messages"%> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/channels/pm/num_unread diff --git a/content/docs/resources/channel/muting.md b/content/docs/resources/channel/muting.md index 8c00c35..20dfb48 100644 --- a/content/docs/resources/channel/muting.md +++ b/content/docs/resources/channel/muting.md @@ -17,11 +17,7 @@ This endpoint is not paginated and does not respond to the [general channel para <%= endpoint "GET", "users/me/channels/muted", "User", "public_messages or messages"%> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/channels/muted @@ -74,28 +70,11 @@ Mute a Channel. If a user doesn't want to see a channel until there is a new mes <%= endpoint "POST", "channels/[channel_id]/mute", "User", "public_messages or messages"%> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel to mute
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel to mute."] +]%> + +#### Example > POST https://alpha-api.app.net/stream/0/channels/1/mute @@ -139,34 +118,17 @@ Mute a Channel. If a user doesn't want to see a channel until there is a new mes ## Unmute a Channel -Unmute from a Channel. This allows you to be resubscribed to the channel (but it does not happen automatically). +Unmute a Channel. This allows you to be resubscribed to the channel (but it does not happen automatically). <%= migration_warning ['response_envelope'] %> <%= endpoint "DELETE", "channels/[channel_id]/mute", "User", "public_messages     or messages"%> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel to unmute
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel to unmute."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/channels/1/mute diff --git a/content/docs/resources/channel/subscriptions.md b/content/docs/resources/channel/subscriptions.md index e35b64e..4df43c8 100644 --- a/content/docs/resources/channel/subscriptions.md +++ b/content/docs/resources/channel/subscriptions.md @@ -17,11 +17,7 @@ This endpoint responds to [pagination parameters](/docs/resources/post/#general- <%= endpoint "GET", "channels", "User", "public_messages     or messages"%> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/channels @@ -76,30 +72,13 @@ Subscribe to a Channel. This adds it to your [Channel stream](#get-current-users <%= endpoint "POST", "channels/[channel_id]/subscribe", "User", "public_messages or messages"%> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel to update
    - -### Example - -> POST https://alpha-api.app.net/stream/0/channels/[channel_id]/subscribe +<%= url_params [ + ["channel_id", "The id of the Channel to subscribe to."] +]%> + +#### Example + +> POST https://alpha-api.app.net/stream/0/channels/1/subscribe ~~~ js { @@ -146,30 +125,13 @@ Unsubscribe from a Channel. This removes it from your [Channel stream](#get-curr <%= endpoint "DELETE", "channels/[channel_id]/subscribe", "User", "public_messages     or messages"%> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel to update
    - -### Example - -> DELETE https://alpha-api.app.net/stream/0/channels/[channel_id]/subscribe +<%= url_params [ + ["channel_id", "The id of the Channel to unsubscribe from."] +]%> + +#### Example + +> DELETE https://alpha-api.app.net/stream/0/channels/1/subscribe ~~~ js { @@ -218,28 +180,11 @@ This endpoint responds to [pagination parameters](/docs/resources/post/#general- <%= endpoint "GET", "channels/[channel_id]/subscribers", "User", "public_messages     or messages"%> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel to request
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel to retrieve subscribers for."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/channels/1/subscribers @@ -318,28 +263,11 @@ Retrieve all the user ids who are subscribed to a Channel. <%= endpoint "GET", "channels/[channel_id]/subscribers/ids", "User", "public_messages     or messages"%> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel to update
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel to retrieve subscriber ids for."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/channels/1/subscribers @@ -357,34 +285,17 @@ Retrieve all the user ids who are subscribed to a Channel. ## Retrieve user ids subscribed to multiple Channels -Retrieve all the user ids who are subscribed to multiple Channels. Up to 200 channels may be requested at one time. Channels which do not exist or which the requesting user does not have authorization to view will not be returned. +For each requested Channel, retrieve the ids of all Users who are subscribed to that Channel. Up to 200 Channels may be requested at one time. Channels which do not exist or which the requesting user does not have authorization to view will not be returned. <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "channels/subscribers/ids", "User", "public_messages     or messages"%> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredintA comma separated list of Channel ids to retrieve.
    - -### Example +<%= query_params [ + ["ids", "A comma separated list of Channel ids to retrieve subscriber ids for."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/channels/subscribers/ids?ids=1,2,3,5 diff --git a/content/docs/resources/explore/index.md b/content/docs/resources/explore/index.md index 5f946d4..c196840 100644 --- a/content/docs/resources/explore/index.md +++ b/content/docs/resources/explore/index.md @@ -56,11 +56,7 @@ Retrieve a list of all Explore Streams. The list of Explore Streams are dynamic <%= endpoint "GET", "posts/stream/explore", "None" %> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/posts/stream/explore @@ -89,28 +85,11 @@ Retrieve the Posts in an Explore Stream. <%= endpoint "GET", "posts/stream/explore/[slug]", "None" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    slugRequiredstringThe slug for this Explore Stream.
    +<%= url_params [ + ["slug", "The slug of the Explore Stream to retrieve."] +]%> -### Example +#### Example > GET https://alpha-api.app.net/stream/0/posts/stream/explore/photos diff --git a/content/docs/resources/file/content.md b/content/docs/resources/file/content.md index bd32495..eefb703 100644 --- a/content/docs/resources/file/content.md +++ b/content/docs/resources/file/content.md @@ -19,26 +19,9 @@ This endpoint will return a 302 Redirect to a temporary URL for the content of t <%= file_token_reminder %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    file_idRequiredstringThe file id.
    +<%= url_params [ + ["file_id", "The id of the File to retrieve content for."] +]%> ## Set File content @@ -52,28 +35,11 @@ This endpoint could return a `507 Insufficient Storage` error if the user doesn' <%= file_token_reminder %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    file_idRequiredstringThe file id.
    - -### Example +<%= url_params [ + ["file_id", "The id of the File to set content for."] +]%> + +#### Example > PUT https://alpha-api.app.net/stream/0/files/1/content > diff --git a/content/docs/resources/file/lifecycle.md b/content/docs/resources/file/lifecycle.md index 1e7a9e2..194aab9 100644 --- a/content/docs/resources/file/lifecycle.md +++ b/content/docs/resources/file/lifecycle.md @@ -23,11 +23,7 @@ When creating a complete file, this endpoint could return a `507 Insufficient St <%= file_token_reminder %> -### Data - -None. - -### Example +#### Example ~~~ POST https://alpha-api.app.net/stream/0/files @@ -72,28 +68,11 @@ Updates a specific [File](/docs/resources/file/) object. You can update a file b <%= file_token_reminder %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    file_idRequiredstringThe id of the File to update
    - -### Example +<%= url_params [ + ["file_id", "The id of the File to update."] +]%> + +#### Example > PUT https://alpha-api.app.net/stream/0/files/1 > @@ -115,28 +94,11 @@ Delete a file. The current user must be the same user who created the File. It r <%= file_token_reminder %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    file_idRequiredstringThe id of the File you'd like to delete
    - -### Example +<%= url_params [ + ["file_id", "The id of the File to delete."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/files/1 diff --git a/content/docs/resources/file/lookup.md b/content/docs/resources/file/lookup.md index 3582d23..e9d98f2 100644 --- a/content/docs/resources/file/lookup.md +++ b/content/docs/resources/file/lookup.md @@ -17,34 +17,18 @@ Returns a specific [File](/docs/resources/file/). <%= file_token_reminder %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    file_idRequiredstringThe file id
    - -### Example +<%= url_params [ + ["file_id", "The id of the File to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/files/1 <%= response(:file) %> ## Retrieve multiple Files + Returns multiple Files requested by id. At most 200 files can be requested. Files which do not exist or which the requesting user does not have authorization to view will not be returned. <%= migration_warning ['response_envelope'] %> @@ -53,28 +37,11 @@ Returns multiple Files requested by id. At most 200 files can be requested. File <%= file_token_reminder %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of File ids to retrieve.
    - -### Example +<%= query_params [ + ["ids", "A comma separated list of File ids to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/files?ids=1,2,6502 @@ -86,17 +53,14 @@ Returns multiple Files requested by id. At most 200 files can be requested. File } %> ## Retrieve my Files + Returns a stream of all Files the current user has created. This endpoint responds to [pagination parameters](/docs/resources/post/#general-parameters) and the [general file parameters](/docs/resources/file/#general-parameters). <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/me/files", "User", "files"%> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/files diff --git a/content/docs/resources/filter/lifecycle.md b/content/docs/resources/filter/lifecycle.md index a9922f1..b84181f 100644 --- a/content/docs/resources/filter/lifecycle.md +++ b/content/docs/resources/filter/lifecycle.md @@ -17,11 +17,11 @@ Send a JSON document that matches the [Filter schema](/docs/resources/filter/) w <%= endpoint "POST", "filters", "User" %> -### Data +#### Data A JSON object representing the [Filter](/docs/resources/filter/) to create. -### Example +#### Example > POST https://alpha-api.app.net/stream/0/filters > @@ -58,28 +58,11 @@ Returns a specific [Filter](/docs/resources/filter/) object. <%= endpoint "GET", "filters/[filter_id]", "User" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    filter_idRequiredstringThe filter id
    - -### Example +<%= url_params [ + ["filter_id", "The id of the Filter to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/filters/1 @@ -112,11 +95,7 @@ Return the [Filter](/docs/resources/filter/) for the current user. <%= endpoint "GET", "filters", "User" %> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/filters @@ -155,28 +134,11 @@ Updates a specific [Filter](/docs/resources/filter/) object. When a filter is up <%= endpoint "PUT", "filters/[filter_id]", "User" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    filter_idRequiredstringThe filter id
    - -### Example +<%= url_params [ + ["filter_id", "The id of the Filter to update."] +]%> + +#### Example > PUT https://alpha-api.app.net/stream/0/filters/1 > @@ -221,28 +183,11 @@ Delete a [Filter](/docs/resources/filter/). The Filter must belong to the curren <%= endpoint "DELETE", "filters/[filter_id]", "User" %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    filter_idRequiredstringThe filter id
    - -### Example +<%= url_params [ + ["filter_id", "The id of the Filter to delete."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/filters/1 @@ -277,11 +222,7 @@ Delete all [Filters](/docs/resources/filter/) for the current user. It returns t <%= endpoint "DELETE", "filters", "User" %> -### Data - -None. - -### Example +#### Example > DELETE https://alpha-api.app.net/stream/0/filters diff --git a/content/docs/resources/interaction/index.md b/content/docs/resources/interaction/index.md index 6141b92..483dd3f 100644 --- a/content/docs/resources/interaction/index.md +++ b/content/docs/resources/interaction/index.md @@ -99,11 +99,7 @@ List all the [Interactions](/docs/resources/interaction/) other users have had w <%= endpoint "GET", "users/me/interactions", "User" %> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/interactions diff --git a/content/docs/resources/message/lifecycle.md b/content/docs/resources/message/lifecycle.md index 6eaead6..b015b41 100644 --- a/content/docs/resources/message/lifecycle.md +++ b/content/docs/resources/message/lifecycle.md @@ -25,28 +25,11 @@ To create private group messages for use in `net.app.core.pm` channels, you can <%= endpoint "POST", "channels/[channel_id]/messages", "User", "public_messages     or messages" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel in which to create the Message. Alternatively, you can specify pm to auto-create/reuse a net.app.core.pm private message channel.
    - -### Generic Channel Example +<%= url_params [ + ["channel_id", 'The id of the Channel in which to create the Message. Alternatively, you can specify pm to auto-create/reuse a net.app.core.pm private message channel.'] +]%> + +#### Generic Channel Example > POST https://alpha-api.app.net/stream/0/channels/1/messages > @@ -85,7 +68,7 @@ To create private group messages for use in `net.app.core.pm` channels, you can } ~~~ -### PM Channel Example +#### PM Channel Example > POST https://alpha-api.app.net/stream/0/channels/pm/messages > > Content-Type: application/json @@ -135,34 +118,12 @@ Delete a message. The current user must be the same user who created the Message <%= endpoint "DELETE", "channels/[channel_id]/messages/[message_id]", "User", "public_messages     or messages" %> -### Data - - - - - - - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel this message belongs to
    message_idRequiredintThe id of the Message you'd like to delete
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel this Message belongs to."], + ["message_id", "The id of the Message to delete."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/channels/1/messages/103 @@ -205,28 +166,11 @@ Retrieve a stream of the Messages in a channel. This endpoint responds to [pagin <%= endpoint "GET", "channels/[channel_id]/messages", "User", "public_messages     or messages" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredintThe id of the Channel who's messages you want to see
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel to retrieve Messages from."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/channels/1/messages diff --git a/content/docs/resources/message/lookup.md b/content/docs/resources/message/lookup.md index f94d545..0c6cfd6 100644 --- a/content/docs/resources/message/lookup.md +++ b/content/docs/resources/message/lookup.md @@ -17,34 +17,12 @@ Returns a specific [Message](/docs/resources/message/). <%= endpoint "GET", "channels/[channel_id]/messages/[message_id]", "User", "public_messages     or messages" %> -### Parameters - - - - - - - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    channel_idRequiredstringThe channel id
    message_idRequiredstringThe message id
    - -### Example +<%= url_params [ + ["channel_id", "The id of the Channel containing the Message."], + ["message_id", "The id of the Message to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/channels/2/messages/480 @@ -80,34 +58,18 @@ Returns a specific [Message](/docs/resources/message/). ~~~ ## Retrieve multiple Messages + Returns multiple Messages requested by id. At most 200 messages can be requested. Messages may be requested from more than one channel at a time. Messages which do not exist or which the requesting user does not have authorization to view will not be returned. <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "channels/messages", "User", "public_messages     or messages" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of Message ids to retrieve.
    - -### Example +<%= query_params [ + ["ids", "A comma separated list of ids of the Messages to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/channels/messages?ids=480,481 @@ -153,11 +115,7 @@ Retrieve a stream of the Messages the current user has created. This endpoint re <%= endpoint "GET", "users/me/messages", "User", "public_messages     or messages" %> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/messages diff --git a/content/docs/resources/place/index.md b/content/docs/resources/place/index.md index 22045ac..0e5675c 100644 --- a/content/docs/resources/place/index.md +++ b/content/docs/resources/place/index.md @@ -170,17 +170,17 @@ Returns info about a Place object with a given `factual_id`. ### Deduplication effects -Because it is possible for duplicate entries to exist for the same Place, Factual provides a method to deduplicate one Place object by "replacing" it with another. As a result, you may notice sometimes that when requesting a Place with one `factual_id` you will get back an entry with a different `factual_id`. When we return a different Place than the one you requested, we are claiming, to the best of our knowledge, that it is equivalent to the one requested. +Because it is possible for duplicate entries to exist for the same Place, Factual provides a method to deduplicate one Place object by "replacing" it with another. As a result, you may notice sometimes that when requesting a Place with one `factual_id` you will get back an entry with a different `factual_id`. When we return a different Place than the one you requested we are claiming, to the best of our knowledge, that it is equivalent to the one requested. <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "places/[factual_id]", "Any" %> -### Parameters +<%= url_params [ + ["factual_id", "The Factual id of the Place to retrieve."] +]%> -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/places/19931850-dc2f-012e-561d-003048cad9da @@ -232,70 +232,27 @@ Returns a list of Places sorted by distance or distance/string match if `q` is p <%= endpoint "GET", "places/search", "User" %> -### Parameters +<%= query_params_typed [ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    latitudeRequireddecimalLatitude of search location. Combined with longitude to create central point of search results.
    longitudeRequireddecimalLongitude of search location. Combined with latitude to create central point of search results.
    qOptionalstringThe name-based search query. Can be a partial string — for example, 'cre' will find any local 'creameries' and 'ice cream' locations.
    radiusOptionaldecimalApproximate radius (in meters) of bounding circle on results. For example, supplying radius=100 will limit all locations to be within 100 meters. Defaults to 100, ranges between 0.001 and 50,000.
    countOptionalintNumber of results to return. Defaults to 20, ranges between 1 and 100.
    altitudeOptionaldecimalAltitude of search location (in meters). Not presently used to generate search results but may be later.
    horizontal_accuracyOptionaldecimalAccuracy of latitude/longitude parameters (in meters). Not presently used to generate search results but may be later.
    vertical_accuracyOptionaldecimalAccuracy of altitude parameter (in meters). Not presently used to generate search results but may be later.
    + ["latitude", "decimal", "Latitude of search location. Combined with longitude to create central point of search results."], + + ["longitude", "decimal", "Longitude of search location. Combined with latitude to create central point of search results."], + + ["q", "string", "(Optional) The name-based search query. Can be a partial string — for example, 'cre' will find any local 'creameries' and 'ice cream' locations."], + + ["radius", "decimal", "(Optional) Approximate radius (in meters) of bounding circle on results. For example, supplying radius=100 will limit all locations to be within 100 meters. Defaults to 100, ranges between 0.001 and 50,000."], -### Example (no search string) + ["count", "int", "(Optional) Number of results to return. Defaults to 20, ranges between 1 and 100."], + + ["altitude", "decimal", "(Optional) Altitude of search location (in meters). Not presently used to generate search results but may be later."], + + ["horizontal_accuracy", "decimal", "(Optional) Accuracy of latitude/longitude parameters (in meters). Not presently used to generate search results but may be later."], + + ["vertical_accuracy", "decimal", "(Optional) Accuracy of altitude parameter (in meters). Not presently used to generate search results but may be later."] + +]%> + +#### Example (no search string) > GET https://alpha-api.app.net/stream/0/places/search?latitude=37.761334&longitude=-122.426276 ~~~ js @@ -351,7 +308,9 @@ Returns a list of Places sorted by distance or distance/string match if `q` is p } ~~~ -### Example (search string, radius and count) +
    + +#### Example (search string, radius and count) > GET https://alpha-api.app.net/stream/0/places/search?latitude=37.78592&longitude=-122.400751&q=bi-rite&count=1&radius=5000 ~~~ js diff --git a/content/docs/resources/post/lifecycle.md b/content/docs/resources/post/lifecycle.md index ea2ec28..c790aa5 100644 --- a/content/docs/resources/post/lifecycle.md +++ b/content/docs/resources/post/lifecycle.md @@ -21,34 +21,12 @@ If you want to test how your text will be processed you can use the [text proces <%= endpoint "POST", "posts", "User", "write_post" %> -### Data - - - - - - - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    textRequiredstringThe raw text of the post
    reply_toOptionalstringThe id of the post that this new post is replying to
    - -### Example +<%= post_params [ + ["text", "The raw text of the post."], + ["reply_to", "(Optional) The id of the Post that this new Post is replying to."] +]%> + +#### Example > POST https://alpha-api.app.net/stream/0/posts > @@ -98,7 +76,9 @@ If you want to test how your text will be processed you can use the [text proces } ~~~ -### JSON Example +
    + +#### Example (JSON Data) > POST https://alpha-api.app.net/stream/0/posts?include_post_annotations=1 > @@ -167,30 +147,13 @@ Delete a Post. The current user must be the <%= migration_warning ['response_envelope'] %> -<%= endpoint "DELETE", "posts", "User", "write_post" %> - -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +<%= endpoint "DELETE", "posts/[post_id]", "User", "write_post" %> + +<%= url_params [ + ["post_id", "The id of the Post to delete."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/posts/1 diff --git a/content/docs/resources/post/lookup.md b/content/docs/resources/post/lookup.md index d6ce362..f519519 100644 --- a/content/docs/resources/post/lookup.md +++ b/content/docs/resources/post/lookup.md @@ -15,28 +15,11 @@ Returns a specific [Post](/docs/resources/post/). <%= endpoint "GET", "posts/[post_id]", "None" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +<%= url_params [ + ["post_id","The id of the Post to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/posts/1 @@ -90,34 +73,18 @@ Returns a specific [Post](/docs/resources/post/). ~~~ ## Retrieve multiple Posts + Returns multiple Posts requested by id. At most 200 posts can be requested. <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of Post ids to retrieve.
    - -### Example +<%= query_params [ + ["ids","A comma separated list of ids of Posts to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/posts?ids=1,2,3 diff --git a/content/docs/resources/post/replies.md b/content/docs/resources/post/replies.md index 344e86f..844ac19 100644 --- a/content/docs/resources/post/replies.md +++ b/content/docs/resources/post/replies.md @@ -11,36 +11,19 @@ title: "Post Replies" Retrieve all the [Posts](/docs/resources/post/) that are in the same thread as this post. The specified Post does not have to be the root of the conversation. Additionally, the specified Post will be included in the response at the appropriate place. -**This endpoint would be more accurately named ```stream/0/posts/[post_id]/thread``` and may be renamed in a later API version.** +**This endpoint would be more accurately named ```stream/0/posts/{post_id}/thread``` and may be renamed in a later API version.** <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts/[post_id]/replies", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    +<%= url_params [ + ["post_id","The id of a Post in the thread to retrieve."] +]%> *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/posts/1/replies diff --git a/content/docs/resources/post/report.md b/content/docs/resources/post/report.md index 3fe3e24..d6a1409 100644 --- a/content/docs/resources/post/report.md +++ b/content/docs/resources/post/report.md @@ -17,28 +17,11 @@ Report a post as spam. This will mute the author of the post and send a report t <%= endpoint "POST", "posts/[post_id]/report", "User" %> -### Data +<%= url_params [ + ["post_id", "The id of the Post to report."] +]%> - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +#### Example > POST https://alpha-api.app.net/stream/0/posts/1/report diff --git a/content/docs/resources/post/reposts.md b/content/docs/resources/post/reposts.md index 2ee4078..727ac33 100644 --- a/content/docs/resources/post/reposts.md +++ b/content/docs/resources/post/reposts.md @@ -21,28 +21,11 @@ For compatibility with clients who don't wish to show reposts specially, we set <%= endpoint "POST", "posts/[post_id]/repost", "User", "write_post" %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +<%= url_params [ + ["post_id", "The id of the Post to repost."] +]%> + +#### Example > POST https://alpha-api.app.net/stream/0/posts/1/repost @@ -121,28 +104,11 @@ Given the original ```post_id```, delete the current user's repost. *Note: this <%= endpoint "DELETE", "posts/[post_id]/repost", "User", "write_post" %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +<%= url_params [ + ["post_id", "The id of the Post to unrepost."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/posts/1/repost diff --git a/content/docs/resources/post/stars.md b/content/docs/resources/post/stars.md index 884badb..838325e 100644 --- a/content/docs/resources/post/stars.md +++ b/content/docs/resources/post/stars.md @@ -17,28 +17,11 @@ Save a given Post to the current User's stars. This is just a "save" action, not <%= endpoint "POST", "posts/[post_id]/star", "User", "write_post" %> -### Data +<%= url_params [ + ["post_id", "The id of the Post to star."] +]%> - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +#### Example > POST https://alpha-api.app.net/stream/0/posts/1/star @@ -99,28 +82,11 @@ Remove a Star from a Post. <%= endpoint "DELETE", "posts/[post_id]/star", "User", "write_post" %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    +<%= url_params [ + ["post_id", "The id of the Post to unstar."] +]%> -### Example +#### Example > DELETE https://alpha-api.app.net/stream/0/posts/1/star @@ -181,30 +147,13 @@ Get the most recent [Posts](/docs/resources/post/) starred by a specific [User]( <%= endpoint "GET", "users/[user_id]/stars", "None" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    +<%= url_params [ + ["user_id", "The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/1/stars diff --git a/content/docs/resources/post/streams.md b/content/docs/resources/post/streams.md index 9449594..b8614a4 100644 --- a/content/docs/resources/post/streams.md +++ b/content/docs/resources/post/streams.md @@ -15,11 +15,11 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the Global stream. <%= endpoint "GET", "posts/stream/global", "None" %> -### Parameters +#### Parameters *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/posts/stream/global @@ -88,30 +88,13 @@ Get the most recent [Posts](/docs/resources/post/) created by a specific [User]( <%= endpoint "GET", "users/[user_id]/posts", "None" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    +<%= url_params [ + ["user_id", "The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/1/posts @@ -178,30 +161,13 @@ Get the most recent [Posts](/docs/resources/post/) mentioning by a specific [Use <%= endpoint "GET", "users/[user_id]/mentions", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    +<%= url_params [ + ["user_id", "The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/2/mentions @@ -268,11 +234,11 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current User a <%= endpoint "GET", "posts/stream", "User", "stream" %> -### Parameters +#### Parameters *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/posts/stream @@ -339,11 +305,11 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current user's <%= endpoint "GET", "posts/stream/unified", "User", "stream" %> -### Parameters +#### Parameters *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/posts/stream/unified @@ -410,11 +376,11 @@ Return the 20 most recent [Posts](/docs/resources/post/) for a specific hashtag. <%= endpoint "GET", "posts/tag/[hashtag]", "None" %> -### Parameters +#### Parameters *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/posts/tag/newsocialnetwork diff --git a/content/docs/resources/stream-marker/index.md b/content/docs/resources/stream-marker/index.md index ce9c857..a337ce1 100644 --- a/content/docs/resources/stream-marker/index.md +++ b/content/docs/resources/stream-marker/index.md @@ -84,11 +84,7 @@ The `last_read_id` is updated if the provided `id` is larger than the current va <%= endpoint "POST", "posts/marker", "User" %> -### Data - -None. - -### Example +#### Example > POST https://alpha-api.app.net/stream/0/posts/marker > diff --git a/content/docs/resources/stream/lifecycle.md b/content/docs/resources/stream/lifecycle.md index 1089a45..e468526 100644 --- a/content/docs/resources/stream/lifecycle.md +++ b/content/docs/resources/stream/lifecycle.md @@ -17,11 +17,11 @@ Send a JSON document that matches the [stream schema](/docs/resources/stream/) w <%= endpoint "POST", "streams", "App" %> -### Data +#### POST Data A JSON object representing the stream to create. See [the stream object](/docs/resources/stream/) for more information. Specify ```filter_id``` instead of ```filter``` if you want to filter this stream. (Omit the ```id``` and ```endpoint``` parameters). -### Example +#### Example > POST https://alpha-api.app.net/stream/0/streams > @@ -67,28 +67,11 @@ Returns a specific [Stream](/docs/resources/stream/) object. <%= endpoint "GET", "streams/[stream_id]", "App" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    stream_idRequiredstringThe stream id
    - -### Example +<%= url_params [ + ["stream_id", "The id of the Stream to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/streams/1 @@ -129,28 +112,11 @@ Return the [Streams](/docs/resources/stream/) for the current token. <%= endpoint "GET", "streams", "App" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    keyOptionalstringOnly retrieve the stream that matches the given key
    - -### Example +<%= query_params [ + ["key", "(Optional) Only retrieve the stream that matches the given key."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/streams?key=rollout_stream @@ -198,28 +164,11 @@ Update a [Stream](/docs/resources/stream/). You can update a Stream by PUTing a <%= endpoint "PUT", "streams/[stream_id]", "App" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    stream_idRequiredstringThe stream id
    - -### Example +<%= url_params [ + ["stream_id", "The id of the Stream to update."] +]%> + +#### Example > PUT https://alpha-api.app.net/stream/0/streams/1 > @@ -268,28 +217,11 @@ Delete a [Stream](/docs/resources/stream/). The Stream must belong to the curren <%= endpoint "DELETE", "streams/[stream_id]", "App" %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    stream_idRequiredstringThe stream id
    - -### Example +<%= url_params [ + ["stream_id", "The id of the Stream to delete."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/streams/1 @@ -332,11 +264,7 @@ Delete all [Streams](/docs/resources/stream/) for the current token. It returns <%= endpoint "DELETE", "streams", "App" %> -### Data - -None. - -### Example +#### Example > DELETE https://alpha-api.app.net/stream/0/streams diff --git a/content/docs/resources/text-processor/index.md b/content/docs/resources/text-processor/index.md index b681be4..cdc3dd4 100644 --- a/content/docs/resources/text-processor/index.md +++ b/content/docs/resources/text-processor/index.md @@ -15,28 +15,11 @@ When a request is made to [create a Post](/docs/resources/post/lifecycle/#create <%= endpoint "POST", "text/process", "Any" %> -### Data +<%= post_params [ + ["text", "The raw text to process."] +]%> - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    textRequiredstringThe raw text to process
    - -### Example +#### Example > POST https://alpha-api.app.net/stream/0/text/process > diff --git a/content/docs/resources/token/index.md b/content/docs/resources/token/index.md index c97bb90..bc9eabf 100644 --- a/content/docs/resources/token/index.md +++ b/content/docs/resources/token/index.md @@ -15,11 +15,7 @@ Returns info about the current [OAuth access token](/docs/authentication/#access <%= endpoint "GET", "token", "Any" %> -### Parameters - -None. - -### Example +#### Example (App Token) Requested with an app access token: @@ -42,6 +38,10 @@ Requested with an app access token: } ~~~ +
    + +#### Example (User Token) + Requested with a user access token: > GET https://alpha-api.app.net/stream/0/token @@ -135,11 +135,7 @@ Returns a list of ids of Users that have authorized an app. Must be requested us <%= endpoint "GET", "apps/me/tokens/user_ids", "App" %> -### Parameters - -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/apps/me/tokens/user_ids @@ -164,11 +160,9 @@ Returns a list of User tokens corresponding to an app token. Must be requested u <%= endpoint "GET", "apps/me/tokens", "App" %> -### Parameters - *See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* -### Example +#### Example > GET https://alpha-api.app.net/stream/0/apps/me/tokens ~~~ js diff --git a/content/docs/resources/user/following.md b/content/docs/resources/user/following.md index d0dc63c..4c5f613 100644 --- a/content/docs/resources/user/following.md +++ b/content/docs/resources/user/following.md @@ -15,28 +15,11 @@ Returns the User object of the user being fo <%= endpoint "POST", "users/[user_id]/follow", "User", "follow" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id to be followed. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The user id to be followed. You can also specify @username as a user_id."] +]%> + +#### Example > POST https://alpha-api.app.net/stream/0/users/1/follow @@ -111,28 +94,11 @@ Returns the User object of the user being un <%= endpoint "DELETE", "users/[user_id]/follow", "User", "follow" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id to stop following. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The user id to stop following. You can also specify @username as a user_id."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/users/1/follow @@ -205,28 +171,11 @@ Returns a list of User objects the specified <%= endpoint "GET", "users/[user_id]/following", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/2/following @@ -305,28 +254,11 @@ Returns a list of User objects for users fol <%= endpoint "GET", "users/[user_id]/followers", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/2/followers @@ -405,28 +337,11 @@ Returns an array of user ids the specified user is following. <%= endpoint "GET", "users/[user_id]/following/ids", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/1/following/ids @@ -451,28 +366,11 @@ Returns an array of user ids for users following the specified user. <%= endpoint "GET", "users/[user_id]/following/ids", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/1/followers/ids diff --git a/content/docs/resources/user/lookup.md b/content/docs/resources/user/lookup.md index 294fc5f..76f5bc9 100644 --- a/content/docs/resources/user/lookup.md +++ b/content/docs/resources/user/lookup.md @@ -15,28 +15,11 @@ Returns a specific User object. <%= endpoint "GET", "users/[user_id]", "None" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/1 @@ -108,28 +91,11 @@ Returns multiple Users requested by id. At most 200 users can be requested. <%= endpoint "GET", "users", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of User ids to retrieve.
    - -### Example +<%= query_params [ + ["ids","A comma separated list of User ids to retrieve."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users?ids=1,2,3 @@ -163,28 +129,11 @@ Search the App.net userbase. <%= endpoint "GET", "users/search", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    qRequiredstringThe search query. Supports @username or #tag searches as well as normal search terms. Searches username, display name, bio information. Does not search posts.
    - -### Example +<%= query_params [ + ["q","The search query. Supports @username or #tag searches as well as normal search terms. Searches username, display name, bio information. Does not search posts."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/search?q=%23mondaynightdanceparty diff --git a/content/docs/resources/user/muting.md b/content/docs/resources/user/muting.md index eb54983..b3b5ad6 100644 --- a/content/docs/resources/user/muting.md +++ b/content/docs/resources/user/muting.md @@ -15,28 +15,11 @@ Hide all posts for a User in all streams. *Note: if you still explicitly request <%= endpoint "POST", "users/[user_id]/mute", "User", "follow" %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe id of the User to mute. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The id of the User to mute. You can also specify @username as a user_id."] +]%> + +#### Example > POST https://alpha-api.app.net/stream/0/users/1/mute @@ -111,28 +94,11 @@ Stop hiding all posts for a given user. <%= endpoint "DELETE", "users/[user_id]/mute", "User", "follow" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe id of the User to unmute. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The id of the User to mute. You can also specify @username as a user_id."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/users/1/mute @@ -199,17 +165,17 @@ Stop hiding all posts for a given user. ## List muted Users -Retrieve a list of muted users. If you have a [user token](/docs/authentication/#access-tokens) you can request muted users for the current user by using `me` as the requested user id. If you have an [app token](/docs/authentication/#access-tokens) you can request muted users for any user that has authorized your app. +Retrieve a list of muted users. <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/[user_id]/muted", "Any" %> -### Parameters - -None. +<%= url_params [ + ["user_id",'The id of the user to retrieve a list of muted users for. If requested with a user token you can request muted users for the current user by using me as the user id. If requested with an app token you can request muted users for any user that has authorized your app.'] +]%> -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/muted @@ -277,7 +243,6 @@ None. } ~~~ - ## Retrieve muted User IDs for multiple Users Returns a list of muted User ids for each User id requested. At most 200 User ids can be requested. @@ -286,28 +251,11 @@ Returns a list of muted User ids for each User id requested. At most 200 User id <%= endpoint "GET", "users/muted/ids", "App" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of User ids to retrieve muted User ids for
    - -### Example +<%= query_params [ + ["ids","A comma separated list of User ids to retrieve muted User ids for."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/muted/ids?ids=1,2 diff --git a/content/docs/resources/user/post-interactions.md b/content/docs/resources/user/post-interactions.md index 3d8e92c..d4c5d53 100644 --- a/content/docs/resources/user/post-interactions.md +++ b/content/docs/resources/user/post-interactions.md @@ -15,28 +15,11 @@ List all the Users who have reposted a given Post. <%= endpoint "GET", "posts/[post_id]/reposters", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +<%= url_params [ + ["post_id","The id of the target Post."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/posts/1/reposters @@ -112,28 +95,11 @@ List all the Users who have starred a given Post. <%= endpoint "GET", "posts/[post_id]/stars", "Any" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    post_idRequiredstringThe post id
    - -### Example +<%= url_params [ + ["post_id","The id of the target post."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/posts/1/stars diff --git a/content/docs/resources/user/profile.md b/content/docs/resources/user/profile.md index c531809..e8d8fbf 100644 --- a/content/docs/resources/user/profile.md +++ b/content/docs/resources/user/profile.md @@ -17,11 +17,7 @@ If you want to add or update a User's annotations, you may include the optional <%= endpoint "PUT", "users/me", "User", "update_profile" %> -### Data - -None. - -### Example +#### Example > PUT https://alpha-api.app.net/stream/0/users/me?include_user_annotations=1 > @@ -81,28 +77,11 @@ Retrieve a User's avatar image. This endpoint does not require authentication, i <%= endpoint "GET", "users/[user_id]/avatar", "None" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    +<%= url_params [ + ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/avatar > @@ -209,28 +188,11 @@ Retrieve a User's cover image. This endpoint does not require authentication, is <%= endpoint "GET", "users/[user_id]/cover", "None" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id.
    +<%= url_params [ + ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] +]%> -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/cover > diff --git a/layouts/partials/endpoint.md b/layouts/partials/endpoint.md index e852527..a32b592 100644 --- a/layouts/partials/endpoint.md +++ b/layouts/partials/endpoint.md @@ -1,11 +1,11 @@ -### Endpoint +#### Endpoint - - - + + + <% if scope != '' %> <% end %> diff --git a/layouts/partials/parameters-typed.md b/layouts/partials/parameters-typed.md new file mode 100644 index 0000000..6402c42 --- /dev/null +++ b/layouts/partials/parameters-typed.md @@ -0,0 +1,20 @@ +#### <%= header %> + +
    MethodPathTokenMethodURLTokenScope
    + + + + + + + + + <% params.each do |param| %> + + + + + + <% end %> + +
    NameTypeDescription
    <%= param[0] %><%= param[1] %><%= param[2] %>
    \ No newline at end of file diff --git a/layouts/partials/parameters.md b/layouts/partials/parameters.md new file mode 100644 index 0000000..a25a9e9 --- /dev/null +++ b/layouts/partials/parameters.md @@ -0,0 +1,18 @@ +#### <%= header %> + + + + + + + + + + <% params.each do |param| %> + + + + + <% end %> + +
    NameDescription
    <%= param[0] %><%= param[1] %>
    \ No newline at end of file diff --git a/lib/helpers.rb b/lib/helpers.rb index 5732bee..c9529a6 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -18,9 +18,26 @@ def migration_warning(migrations = []) end def endpoint(method, path, token, scope = "") - render '/partials/endpoint', :method => method, :path => '/stream/0/'+path, :token => token, :scope => scope + path = path.gsub('[','{').gsub(']','}') + render '/partials/endpoint', :method => method, :path => 'https://alpha-api.app.net/stream/0/'+path, :token => token, :scope => scope +end + +def url_params(params = []) + render '/partials/parameters', :header => "URL Parameters", :params => params +end + +def query_params(params = []) + render '/partials/parameters', :header => "Query String Parameters", :params => params +end + +def query_params_typed(params = []) + render "/partials/parameters-typed", :header => "Query String Parameters", :params => params +end + +def post_params(params = []) + render "/partials/parameters", :header => "POST Body Data", :params =>params end def file_token_reminder() "
    Please see the File Authorization documentation for more information on User and File tokens.
    " -end +end \ No newline at end of file From 365d8c96d179cea3db68473d77ef064d91a112cb Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Thu, 21 Mar 2013 11:30:44 -0700 Subject: [PATCH 010/231] Fix endpoint typo --- layouts/partials/endpoints/channel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/endpoints/channel.md b/layouts/partials/endpoints/channel.md index bd879eb..2234d92 100644 --- a/layouts/partials/endpoints/channel.md +++ b/layouts/partials/endpoints/channel.md @@ -89,7 +89,7 @@ Unmute a Channel DELETE - /stream/0/channels/[channel_id]/unmute + /stream/0/channels/[channel_id]/mute User From c68363883c4ac5c149a3fccc4df8948ec3ea784d Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Fri, 22 Mar 2013 11:47:35 -0700 Subject: [PATCH 011/231] Tweak blocking docs to use new format --- content/docs/resources/user/blocking.md | 91 ++++++------------------- content/docs/resources/user/muting.md | 2 +- 2 files changed, 21 insertions(+), 72 deletions(-) diff --git a/content/docs/resources/user/blocking.md b/content/docs/resources/user/blocking.md index 4032d7c..8793efb 100644 --- a/content/docs/resources/user/blocking.md +++ b/content/docs/resources/user/blocking.md @@ -17,28 +17,11 @@ In most cases, [muting a user](/docs/resources/user/muting/#mute-a-user) is prob <%= endpoint "POST", "users/[user_id]/block", "User", "follow" %> -### Data - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe id of the User to block. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The id of the User to block. You can also specify @username as a user_id."] +]%> + +#### Example > POST https://alpha-api.app.net/stream/0/users/1/block @@ -114,28 +97,11 @@ Allow a blocked user to interact with my content. <%= endpoint "DELETE", "users/[user_id]/block", "User", "follow" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    user_idRequiredstringThe id of the User to unblock. You can also specify @username as a user_id.
    - -### Example +<%= url_params [ + ["user_id","The id of the User to block. You can also specify @username as a user_id."] +]%> + +#### Example > DELETE https://alpha-api.app.net/stream/0/users/1/block @@ -203,17 +169,17 @@ Allow a blocked user to interact with my content. ## List blocked Users -Retrieve a list of blocked users. If you have a [user token](/docs/authentication/#access-tokens) you can request blocked users for the current user by using `me` as the requested user id. If you have an [app token](/docs/authentication/#access-tokens) you can request blocked users for any user that has authorized your app. +Retrieve a list of blocked users. <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/[user_id]/blocked", "Any" %> -### Parameters +<%= url_params [ + ["user_id",'The id of the user to retrieve a list of muted users for. If requested with a user token you can request blocked users for the current user by using me as the user id. If requested with an app token you can request blocked users for any user that has authorized your app.'] +]%> -None. - -### Example +#### Example > GET https://alpha-api.app.net/stream/0/users/me/blocked @@ -291,28 +257,11 @@ Returns a list of blocked User ids for each User id requested. At most 200 User <%= endpoint "GET", "users/blocked/ids", "App" %> -### Parameters - - - - - - - - - - - - - - - - - - -
    NameRequired?TypeDescription
    idsRequiredstringA comma separated list of User ids to retrieve blocked User ids for
    - -### Example +<%= query_params [ + ["ids","A comma separated list of User ids to retrieve blocked User ids for."] +]%> + +#### Example > GET https://alpha-api.app.net/stream/0/users/blocked/ids?ids=1,2 diff --git a/content/docs/resources/user/muting.md b/content/docs/resources/user/muting.md index b3b5ad6..817d4df 100644 --- a/content/docs/resources/user/muting.md +++ b/content/docs/resources/user/muting.md @@ -165,7 +165,7 @@ Stop hiding all posts for a given user. ## List muted Users -Retrieve a list of muted users. +Retrieve a list of muted users. <%= migration_warning ['response_envelope'] %> From 86062bfcc2fbb3248e2f2142a67cf40becafaccc Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 25 Mar 2013 14:24:14 -0700 Subject: [PATCH 012/231] Add note about blocking not being secret --- content/docs/resources/user/blocking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/user/blocking.md b/content/docs/resources/user/blocking.md index 8793efb..a57ca4b 100644 --- a/content/docs/resources/user/blocking.md +++ b/content/docs/resources/user/blocking.md @@ -9,7 +9,7 @@ title: "User Blocking" ## Block a User -Block a user from seeing your App.net content. This means the user will not be able to see, star, reply to, or repost your content. This user will also effectively be muted for you. This will automatically unfollow both users from each other. +Block a user from seeing your App.net content. This means the user will not be able to see, star, reply to, or repost your content. This user will also effectively be muted for you. This will automatically unfollow both users from each other. A user may be able to tell if they've been blocked by a user. For instance if @mthurman blocks @berg and @berg logs out of alpha.app.net, he could see @mthurman's profile. In most cases, [muting a user](/docs/resources/user/muting/#mute-a-user) is probably sufficient since that hides all of a user's content from you. If a user is aggressively reposting or starring your content, blocking them will prevent them from interacting with your content at all. From c5c4bec3638252bde7dccf63a2594e64217c1f9b Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 25 Mar 2013 16:42:46 -0700 Subject: [PATCH 013/231] Add uri templating to oembed --- content/docs/meta/entities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index 388d4fa..0ba7a0e 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -145,7 +145,7 @@ Links can contain [URI templates](http://tools.ietf.org/html/rfc6570) that the s > photos.app.net/{post_id}/1 -and the server replaces `{post_id}` with the id of the Post once it has been saved. By default, this processing happens on all links (both custom links and links extracted by the API). If you would like a link to not be processed, you can create the link as a [custom link](#links-with-custom-anchor-text) and include `"process_template": False` in the JSON for the link. +and the server replaces `{post_id}` with the id of the Post once it has been saved. By default, this processing happens on all links (both custom links and links extracted by the API). If you would like a link to not be processed, you can create the link as a [custom link](#links-with-custom-anchor-text) and include `"process_template": False` in the JSON for the link. The [Embedded Media Annotation](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) also supports URI templating for some of it's attributes. #### Replacement variables From 84235cd5a991beeba509d4459a41ea1b4013dd9b Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 25 Mar 2013 16:53:50 -0700 Subject: [PATCH 014/231] False -> false --- content/docs/meta/entities.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index 0ba7a0e..3a2d613 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -145,7 +145,7 @@ Links can contain [URI templates](http://tools.ietf.org/html/rfc6570) that the s > photos.app.net/{post_id}/1 -and the server replaces `{post_id}` with the id of the Post once it has been saved. By default, this processing happens on all links (both custom links and links extracted by the API). If you would like a link to not be processed, you can create the link as a [custom link](#links-with-custom-anchor-text) and include `"process_template": False` in the JSON for the link. The [Embedded Media Annotation](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) also supports URI templating for some of it's attributes. +and the server replaces `{post_id}` with the id of the Post once it has been saved. By default, this processing happens on all links (both custom links and links extracted by the API). If you would like a link to not be processed, you can create the link as a [custom link](#links-with-custom-anchor-text) and include `"process_template": false` in the JSON for the link. The [Embedded Media Annotation](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) also supports URI templating for some of it's attributes. #### Replacement variables From 10a0a055659a54854fc7baf62357966bb9ea5b80 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Tue, 26 Mar 2013 16:51:03 -0700 Subject: [PATCH 015/231] Fix endpoint typo --- content/docs/resources/user/following.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/user/following.md b/content/docs/resources/user/following.md index 4c5f613..b9b133b 100644 --- a/content/docs/resources/user/following.md +++ b/content/docs/resources/user/following.md @@ -364,7 +364,7 @@ Returns an array of user ids for users following the specified user. <%= migration_warning ['response_envelope'] %> -<%= endpoint "GET", "users/[user_id]/following/ids", "Any" %> +<%= endpoint "GET", "users/[user_id]/followers/ids", "Any" %> <%= url_params [ ["user_id","The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] From 54c1615fa9105ea2a34423c5a0e5659eb8733761 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Tue, 26 Mar 2013 19:35:07 -0700 Subject: [PATCH 016/231] Removing line numbers in JSON examples --- Rules | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/Rules b/Rules index 3c432e6..f7dca76 100644 --- a/Rules +++ b/Rules @@ -21,9 +21,7 @@ compile '*' do # don’t filter binary items else filter :erb - filter :kramdown, :toc_levels => [2] - filter :colorize_syntax, - :colorizers => {:javascript => :pygmentsrb} + filter :kramdown, :toc_levels => [2], :coderay_line_numbers => nil layout 'default' end end From 146c3f3d7f7bdd99ef45858069302710ecf41753 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Tue, 26 Mar 2013 20:55:06 -0700 Subject: [PATCH 017/231] Style HTTP methods --- layouts/partials/endpoint.md | 2 +- static/css/style.css | 20 ++++++++++++++++---- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/layouts/partials/endpoint.md b/layouts/partials/endpoint.md index a32b592..cef6c80 100644 --- a/layouts/partials/endpoint.md +++ b/layouts/partials/endpoint.md @@ -13,7 +13,7 @@ - <%= method %> + <%= method %> <%= path %> <%= token %> <% if scope != '' %> diff --git a/static/css/style.css b/static/css/style.css index a5a02b4..ba89d23 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -1,9 +1,21 @@ /* we're currently modifying bootstrap.css to apply 'table' and 'table-striped' styles to all tables */ -.line-numbers { - margin-right: 1.0em; -} - .content { padding-bottom: 100px; +} + +.label-GET { + background-color: #3a87ad; +} + +.label-POST { + background-color: #468847; +} + +.label-PUT { + background-color: #f89406; +} + +.label-DELETE { + background-color: #b94a48; } \ No newline at end of file From a9eca8695b5459996b4ca97725e18c15392c8303 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Wed, 27 Mar 2013 11:40:03 -0700 Subject: [PATCH 018/231] Fix example --- content/docs/resources/stream/index.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/content/docs/resources/stream/index.md b/content/docs/resources/stream/index.md index 6dda773..f6368ba 100644 --- a/content/docs/resources/stream/index.md +++ b/content/docs/resources/stream/index.md @@ -494,7 +494,7 @@ A user deauthorizes an application. A file is created. -~~~js +~~~ js { "meta": { "timestamp": 1358986634896, @@ -520,7 +520,7 @@ A file is created. A file is uploaded to (or updated). -~~~js +~~~ js { "meta": { "timestamp": 1358986636754, @@ -568,6 +568,7 @@ A file is uploaded to (or updated). A file is deleted. +~~~ js { "meta": { "timestamp": 1358986636754, @@ -576,5 +577,6 @@ A file is deleted. "is_deleted": true, }, } +~~~ <%= render 'partials/endpoints-tab', :for => "stream" %> From f7636415bd96504bee8bcee85a89310c42905fb1 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Wed, 27 Mar 2013 11:55:39 -0700 Subject: [PATCH 019/231] Add links to object-metadata repo --- content/docs/meta/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index 8b33a36..e4c5095 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -120,7 +120,7 @@ In the `value` of any annotation (including non-core annotations), we treat any ## Documenting annotations -To foster collaboration and adoption, we've set up a github repository for documenting annotations. To discuss annotations, please use the associate issue tracker. For more information on submitting / updating documentation please review the README. +To foster collaboration and adoption, we've set up a [github repository](https://github.com/appdotnet/object-metadata) for documenting annotations. To discuss annotations, please use the associate [issue tracker](https://github.com/appdotnet/object-metadata/issues). For more information on submitting / updating documentation please review the [README](https://github.com/appdotnet/object-metadata). ### Core annotations From b63829ad8f7e89e43b2c0346bc08b613ff868576 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Wed, 27 Mar 2013 12:03:10 -0700 Subject: [PATCH 020/231] Add max 5 streams per App token --- content/docs/resources/stream/index.md | 2 +- content/docs/resources/stream/lifecycle.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/resources/stream/index.md b/content/docs/resources/stream/index.md index f6368ba..58ee094 100644 --- a/content/docs/resources/stream/index.md +++ b/content/docs/resources/stream/index.md @@ -86,7 +86,7 @@ A Stream is a real-time, ordered collection of objects. An object will always be There will be three different kinds of Streams, but they all follow the same pattern: -* Public stream (available now): A Stream containing all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/docs/authentication/flows/app-access-token/)**. +* Public stream (available now): A Stream containing all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/docs/authentication/flows/app-access-token/)**. You can create up to 5 public streams per App token. * User stream (coming soon): A Stream for a single User's view of App.net. This is a Stream version of the [Retrieve a User's personalized stream](/docs/resources/post/streams/#retrieve-a-users-personalized-stream) endpoint. It is very useful for client based Apps that need a single User's Stream. **It must be accessed with a User access token**. diff --git a/content/docs/resources/stream/lifecycle.md b/content/docs/resources/stream/lifecycle.md index e468526..eb491b1 100644 --- a/content/docs/resources/stream/lifecycle.md +++ b/content/docs/resources/stream/lifecycle.md @@ -13,6 +13,8 @@ Create a [Stream](/docs/resources/stream/) for the current token. Send a JSON document that matches the [stream schema](/docs/resources/stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. +You can create up to 5 streams per App token. + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "streams", "App" %> From feba30ac1189639642e5f258be58a7d3d5f03e89 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Thu, 28 Mar 2013 18:05:51 -0700 Subject: [PATCH 021/231] Cleanup docs. Closes #324 #316 --- content/docs/authentication/index.md | 5 ++--- content/docs/resources/file/index.md | 25 +++++++++++++++++++++++++ content/docs/resources/token/index.md | 9 +++++++-- lib/sample_objects.rb | 12 ++++++++++++ 4 files changed, 46 insertions(+), 5 deletions(-) diff --git a/content/docs/authentication/index.md b/content/docs/authentication/index.md index 8af8250..2020f41 100644 --- a/content/docs/authentication/index.md +++ b/content/docs/authentication/index.md @@ -56,15 +56,14 @@ Scopes are how an application specifies what kind of data it wants from a User. When using an OAuth token, App.net will include an extra HTTP headers so the app knows what scopes that token has authorized. For example: -> X-OAuth-Scopes: email,follow +> X-OAuth-Scopes: follow,write_post -means that the current token has permission to see the user's email and to follow new users. +means that the current token has permission to follow new users and to create posts for this user. Here is the current list of scopes on App.net: * **basic**: see basic information about this user * **stream**: read this user's stream -* **email**: access this user's email address * **write_post**: create a new post as this user * **follow**: add or remove follows (or mutes) for this user * **public_messages**: send and receive public messages as this user diff --git a/content/docs/resources/file/index.md b/content/docs/resources/file/index.md index f3379c2..e19632e 100644 --- a/content/docs/resources/file/index.md +++ b/content/docs/resources/file/index.md @@ -59,6 +59,31 @@ A file uploaded by a User and hosted by App.net. string Primary identifier for a File. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed. + + image_info + object + + If this File is an image that App.net can process, then the following information will be included: +
    + + + + + + + + + + + + + + + + +
    FieldTypeDescription
    heightintegerThe height of the image.
    widthintegerThe width of the image.
    + + kind string diff --git a/content/docs/resources/token/index.md b/content/docs/resources/token/index.md index bc9eabf..e64154c 100644 --- a/content/docs/resources/token/index.md +++ b/content/docs/resources/token/index.md @@ -60,9 +60,12 @@ Requested with a user access token: "messages", "export", "write_post", - "follow", - "email" + "follow" ], + "limits": { + "following": 40, + "max_file_size": 10000000 + }, "storage": { "available": 8787479688, "used": 1212520312 @@ -175,6 +178,7 @@ Returns a list of User tokens corresponding to an app token. Must be requested u "name": "app" }, "client_id": "tHkLXfGusVxJ3NtyMYdyvQ9Rh4ZbeL5n", + "limits": { ... }, "scopes": [ "basic" ], @@ -188,6 +192,7 @@ Returns a list of User tokens corresponding to an app token. Must be requested u "name": "app" }, "client_id": "tHkLXfGusVxJ3NtyMYdyvQ9Rh4ZbeL5n", + "limits": { ... }, "scopes": [ "update_profile", "messages", diff --git a/lib/sample_objects.rb b/lib/sample_objects.rb index a35fef6..83242aa 100644 --- a/lib/sample_objects.rb +++ b/lib/sample_objects.rb @@ -45,6 +45,10 @@ def paginated_response(key, &block) "created_at" => "2013-01-28T18:31:18Z", "derived_files" => { "image_thumb_200s" => { + "image_info" => { + "width" => 200, + "height" => 200, + }, "mime_type" => "image/png", "sha1" => "be91cb06d69df13bb103a359ce70cf9fba31234a", "size" => 33803, @@ -52,6 +56,10 @@ def paginated_response(key, &block) "url_expires" => "2013-01-25T03:00:00Z", }, "image_thumb_960r" => { + "image_info" => { + "width" => 600, + "height" => 800, + }, "mime_type" => "image/png", "size" => 140173, "sha1" => "57004b55119002f551be5b9f2d5439dd4ad1234a", @@ -61,6 +69,10 @@ def paginated_response(key, &block) }, "file_token" => "auCj3h64JZrhQ9aJdmwre3KP-QL9UtWHYvt5tj_64rUJWemoIV2W8eTJv9NMaGpBFk-BbU_aWA26Q40w4jFhiPBpnIQ_lciLwfh6o8YIAQGEQziksUMxZo7gOHJ_-niw3l3MZCh7QRWzqNGpiVaUEptfKO0fETrZ8bJjDa61234a", "id" => "1", + "image_info" => { + "width" => 600, + "height" => 800, + }, "kind" => "image", "mime_type" => "image/png", "name" => "filename.png", From 187fb632bbe5a4dbe58867b9be333f522bff2c53 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Fri, 29 Mar 2013 11:39:23 -0700 Subject: [PATCH 022/231] Document all endpoints that respond to general params and / or pagination --- content/docs/resources/channel/index.md | 4 +- content/docs/resources/channel/lifecycle.md | 4 ++ content/docs/resources/channel/lookup.md | 15 ++++--- content/docs/resources/channel/muting.md | 6 ++- .../docs/resources/channel/subscriptions.md | 12 ++++- content/docs/resources/explore/index.md | 2 + content/docs/resources/file/index.md | 4 +- content/docs/resources/file/lifecycle.md | 6 +++ content/docs/resources/file/lookup.md | 10 ++++- content/docs/resources/filter/lifecycle.md | 10 +---- content/docs/resources/interaction/index.md | 3 ++ content/docs/resources/message/index.md | 4 +- content/docs/resources/message/lifecycle.md | 10 ++++- content/docs/resources/message/lookup.md | 10 ++++- content/docs/resources/post/index.md | 4 +- content/docs/resources/post/lifecycle.md | 4 ++ content/docs/resources/post/lookup.md | 4 ++ content/docs/resources/post/replies.md | 6 ++- content/docs/resources/post/report.md | 2 + content/docs/resources/post/reposts.md | 4 ++ content/docs/resources/post/stars.md | 8 ++++ content/docs/resources/post/streams.md | 44 ++++++++++--------- content/docs/resources/token/index.md | 4 +- content/docs/resources/user/blocking.md | 6 +++ content/docs/resources/user/following.md | 14 +++++- content/docs/resources/user/index.md | 4 +- content/docs/resources/user/lookup.md | 6 +++ content/docs/resources/user/muting.md | 8 +++- .../docs/resources/user/post-interactions.md | 4 ++ content/docs/resources/user/profile.md | 5 +++ lib/helpers.rb | 10 ++++- 31 files changed, 185 insertions(+), 52 deletions(-) diff --git a/content/docs/resources/channel/index.md b/content/docs/resources/channel/index.md index 13d0981..36e2b89 100644 --- a/content/docs/resources/channel/index.md +++ b/content/docs/resources/channel/index.md @@ -239,7 +239,7 @@ You can create arbitrary Channel types which do not have these restrictions (but ## General Parameters -Requests that return streams of Channels respond to [pagination parameters](/docs/basics/pagination). Additionally they accept the following query string parameters: +Where noted, Channel endpoints respond to the following query string parameters: @@ -296,4 +296,6 @@ Requests that return streams of Channels respond to [pagination parameters](/doc
    +Where noted, endpoints that return a stream of Channels additionally respond to [pagination parameters](/docs/basics/pagination). + <%= render 'partials/endpoints-tab', :for => "channel" %> diff --git a/content/docs/resources/channel/lifecycle.md b/content/docs/resources/channel/lifecycle.md index 6a2f2b1..e37fbda 100644 --- a/content/docs/resources/channel/lifecycle.md +++ b/content/docs/resources/channel/lifecycle.md @@ -17,6 +17,8 @@ Send a JSON document that matches the [Channel schema](/docs/resources/channel/) [PM Channels](/docs/resources/channel/#private-message) (channels of type `net.app.core.pm`) cannot be directly created. Instead they are created for you as necessary when sending a [Message](/docs/resources/message/) using `pm` as a `channel_id`. For more information, see the [Create a Message](/docs/resources/message/lifecycle/#create-a-message) endpoint. +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "channels", "User", "public_messages     or messages"%> @@ -73,6 +75,8 @@ Updates a specific [Channel](/docs/resources/channel/) object. You can update a If you want to add or update a Channel's annotations, you may include the optional ```annotations``` key and pass in the annotations that are changing. +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "PUT", "channels/[channel_id]", "User", "public_messages or messages"%> diff --git a/content/docs/resources/channel/lookup.md b/content/docs/resources/channel/lookup.md index aafddab..b359b6f 100644 --- a/content/docs/resources/channel/lookup.md +++ b/content/docs/resources/channel/lookup.md @@ -11,6 +11,8 @@ title: "Channel Lookup" Returns a specific [Channel](/docs/resources/channel/). +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "channels/[channel_id]", "User", "public_messages or messages"%> @@ -64,6 +66,8 @@ Returns a specific [Channel](/docs/resources/channel/). ## Retrieve multiple Channels Returns multiple Channels requested by id. At most 200 channels can be requested. Channels which do not exist or which the requesting user does not have authorization to view will not be returned. +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "channels", "User", "public_messages or messages"%> @@ -148,7 +152,11 @@ Returns multiple Channels requested by id. At most 200 channels can be requested ~~~ ## Retrieve my Channels -Returns a stream of all Channels the current user has created. This endpoint responds to [pagination parameters](/docs/resources/post/#general-parameters) and the [general channel parameters](/docs/resources/channel/#general-parameters). +Returns a stream of all Channels the current user has created. + +<%= general_params_note_for "channel" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope'] %> @@ -217,10 +225,7 @@ Returns the current number of `net.app.core.pm` Channels where `has_unread: true { "data": 5, "meta": { - "code": 200, - "max_id": 2, - "min_id": 1, - "more": false + "code": 200 } } ~~~ diff --git a/content/docs/resources/channel/muting.md b/content/docs/resources/channel/muting.md index 20dfb48..b87a766 100644 --- a/content/docs/resources/channel/muting.md +++ b/content/docs/resources/channel/muting.md @@ -11,7 +11,7 @@ title: "Channel Muting" Retrieve a list of the channels the current user has muted. A user cannot be [auto-subscribed](/docs/basics/messaging/#subscriptions) to muted channels. -This endpoint is not paginated and does not respond to the [general channel parameters](/docs/resources/channel/#general-parameters). +This endpoint is **not** paginated and does **not** respond to the [general channel parameters](/docs/resources/channel/#general-parameters). <%= migration_warning ['response_envelope'] %> @@ -66,6 +66,8 @@ This endpoint is not paginated and does not respond to the [general channel para Mute a Channel. If a user doesn't want to see a channel until there is a new message, they should [unsubscribe from the channel](/docs/resources/channel/subscriptions/#unsubscribe-from-a-channel) instead of muting it. If a user mutes a channel, they will automatically be unsubscribed from it and cannot be [auto-subscribed](/docs/basics/messaging/#subscriptions) to it. +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "channels/[channel_id]/mute", "User", "public_messages or messages"%> @@ -120,6 +122,8 @@ Mute a Channel. If a user doesn't want to see a channel until there is a new mes Unmute a Channel. This allows you to be resubscribed to the channel (but it does not happen automatically). +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "DELETE", "channels/[channel_id]/mute", "User", "public_messages or messages"%> diff --git a/content/docs/resources/channel/subscriptions.md b/content/docs/resources/channel/subscriptions.md index 4df43c8..9b486a8 100644 --- a/content/docs/resources/channel/subscriptions.md +++ b/content/docs/resources/channel/subscriptions.md @@ -11,7 +11,9 @@ title: "Channel Subscriptions" Retrieve an "inbox" of the channels the user is currently subscribed to. This stream is ordered like an inbox with the stream containing the most recent post first. -This endpoint responds to [pagination parameters](/docs/resources/post/#general-parameters) and the [general channel parameters](/docs/resources/channel/#general-parameters). Remember that the ```min_id```/```max_id``` for pagination do not have to correspond to the ids in the response's ```data``` list. +<%= general_params_note_for "channel" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope'] %> @@ -68,6 +70,8 @@ This endpoint responds to [pagination parameters](/docs/resources/post/#general- Subscribe to a Channel. This adds it to your [Channel stream](#get-current-users-subscribed-channels). If a user has [muted this Channel](/docs/resources/channel/muting/#mute-a-channel), this call will automatically unmute the Channel. +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "channels/[channel_id]/subscribe", "User", "public_messages or messages"%> @@ -121,6 +125,8 @@ Subscribe to a Channel. This adds it to your [Channel stream](#get-current-users Unsubscribe from a Channel. This removes it from your [Channel stream](#get-current-users-subscribed-channels). +<%= general_params_note_for "channel" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "DELETE", "channels/[channel_id]/subscribe", "User", "public_messages or messages"%> @@ -174,7 +180,9 @@ Unsubscribe from a Channel. This removes it from your [Channel stream](#get-curr Retrieve the users who are subscribed to a Channel. -This endpoint responds to [pagination parameters](/docs/resources/post/#general-parameters). Remember that the ```min_id```/```max_id``` do not have to correspond to the ids in the ```data``` list. +<%= general_params_note_for "channel" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope'] %> diff --git a/content/docs/resources/explore/index.md b/content/docs/resources/explore/index.md index c196840..3df2490 100644 --- a/content/docs/resources/explore/index.md +++ b/content/docs/resources/explore/index.md @@ -81,6 +81,8 @@ Retrieve a list of all Explore Streams. The list of Explore Streams are dynamic Retrieve the Posts in an Explore Stream. +<%= pagination_note %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts/stream/explore/[slug]", "None" %> diff --git a/content/docs/resources/file/index.md b/content/docs/resources/file/index.md index f3379c2..8138741 100644 --- a/content/docs/resources/file/index.md +++ b/content/docs/resources/file/index.md @@ -200,7 +200,7 @@ Paid tier accounts receive 10GB total storage, with a 100MB maximum individual f ## General Parameters -Requests that return streams of Files respond to [pagination parameters](/docs/basics/pagination). Additionally they accept the following query string parameters: +Where noted, File endpoints respond to the following query string parameters: @@ -251,6 +251,8 @@ Requests that return streams of Files respond to [pagination parameters](/docs/b
    +Where noted, endpoints that return a stream of Files additionally respond to [pagination parameters](/docs/basics/pagination). + ## Attaching Files to other resources An App.net file can be attached to any resource that allows annotations. You can attach a file to a resource with any annotation by using the [annotation replacement values](/docs/meta/annotations/#annotation-replacement-values). For instance, to attach a photo that you've uploaded as a file to a new post, you would send the following annotations when making your post: diff --git a/content/docs/resources/file/lifecycle.md b/content/docs/resources/file/lifecycle.md index 194aab9..b677046 100644 --- a/content/docs/resources/file/lifecycle.md +++ b/content/docs/resources/file/lifecycle.md @@ -17,6 +17,8 @@ You can also create a complete File object with one request by including the fil When creating a complete file, this endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/docs/resources/file/#limits). +<%= general_params_note_for "file" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "files", "User" %> @@ -62,6 +64,8 @@ Here is some [sample File upload code written in Python](https://gist.github.com Updates a specific [File](/docs/resources/file/) object. You can update a file by PUTing an object that matches the [File schema](/docs/resources/file/) with an HTTP header of `Content-Type: application/json`. The only keys that can be updated are `annotations`, `name` and `public`. Only the File owner can update a File. +<%= general_params_note_for "file" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "PUT", "files/[file_id]", "User"%> @@ -88,6 +92,8 @@ Delete a file. The current user must be the same user who created the File. It r *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +<%= general_params_note_for "file" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "DELETE", "files/[file_id]", "User" %> diff --git a/content/docs/resources/file/lookup.md b/content/docs/resources/file/lookup.md index e9d98f2..260280d 100644 --- a/content/docs/resources/file/lookup.md +++ b/content/docs/resources/file/lookup.md @@ -11,6 +11,8 @@ title: "File Lookup" Returns a specific [File](/docs/resources/file/). +<%= general_params_note_for "file" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "files/[file_id]", "Varies"%> @@ -31,6 +33,8 @@ Returns a specific [File](/docs/resources/file/). Returns multiple Files requested by id. At most 200 files can be requested. Files which do not exist or which the requesting user does not have authorization to view will not be returned. +<%= general_params_note_for "file" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "files", "User", "files"%> @@ -54,7 +58,11 @@ Returns multiple Files requested by id. At most 200 files can be requested. File ## Retrieve my Files -Returns a stream of all Files the current user has created. This endpoint responds to [pagination parameters](/docs/resources/post/#general-parameters) and the [general file parameters](/docs/resources/file/#general-parameters). +Returns a stream of all Files the current user has created. + +<%= general_params_note_for "file" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope'] %> diff --git a/content/docs/resources/filter/lifecycle.md b/content/docs/resources/filter/lifecycle.md index b84181f..3f6e784 100644 --- a/content/docs/resources/filter/lifecycle.md +++ b/content/docs/resources/filter/lifecycle.md @@ -118,10 +118,7 @@ Return the [Filter](/docs/resources/filter/) for the current user. ... ], "meta": { - "code": 200, - "max_id": "2", - "min_id": "1", - "more": false + "code": 200 } } ~~~ @@ -245,10 +242,7 @@ Delete all [Filters](/docs/resources/filter/) for the current user. It returns t ... ], "meta": { - "code": 200, - "max_id": "2", - "min_id": "1", - "more": false + "code": 200 } } ~~~ diff --git a/content/docs/resources/interaction/index.md b/content/docs/resources/interaction/index.md index 483dd3f..ecc4fd6 100644 --- a/content/docs/resources/interaction/index.md +++ b/content/docs/resources/interaction/index.md @@ -90,11 +90,14 @@ Interactions are objects that represent users taking certain actions on App.net. List all the [Interactions](/docs/resources/interaction/) other users have had with me. +<%= pagination_note %> + > Note: you can only request this list for the current user. > Note: although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/docs/resources/stream/) to monitor the global feed for relevant activity. + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/me/interactions", "User" %> diff --git a/content/docs/resources/message/index.md b/content/docs/resources/message/index.md index 07462d9..c07c55e 100644 --- a/content/docs/resources/message/index.md +++ b/content/docs/resources/message/index.md @@ -146,7 +146,7 @@ Sometimes a Message is not meant for human consumption but it may be readable by ## General Parameters -Requests that return streams of Messages respond to [pagination parameters](/docs/basics/pagination). Additionally they accept the following query string parameters: +Where noted, Message endpoints respond to the following query string parameters: @@ -197,4 +197,6 @@ Requests that return streams of Messages respond to [pagination parameters](/doc
    +Where noted, endpoints that return a stream of Messages additionally respond to [pagination parameters](/docs/basics/pagination). + <%= render 'partials/endpoints-tab', :for => "message" %> diff --git a/content/docs/resources/message/lifecycle.md b/content/docs/resources/message/lifecycle.md index b015b41..8eef887 100644 --- a/content/docs/resources/message/lifecycle.md +++ b/content/docs/resources/message/lifecycle.md @@ -21,6 +21,8 @@ If you want to test how your text will be processed you can use the [text proces To create private group messages for use in `net.app.core.pm` channels, you can specify the special `channel_id` of `pm`. With this parameter, the server will look for an extra field in the provided message object called `destinations` which is a list of user ids to send this message to. If a private message channel already exists between this group of users, its `channel_id` will be reused. Otherwise, a new channel will be created and the users specified in the `destinations` list will be auto-subscribed (according to their [subscription preferences](https://account.app.net/settings/messaging-permissions/)) and able to write to that channel. Note that the `destinations` value may include user ids in the form of "@username" or integer id. +<%= general_params_note_for "message" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "channels/[channel_id]/messages", "User", "public_messages     or messages" %> @@ -114,6 +116,8 @@ Delete a message. The current user must be the same user who created the Message *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +<%= general_params_note_for "message" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "DELETE", "channels/[channel_id]/messages/[message_id]", "User", "public_messages or messages" %> @@ -160,7 +164,11 @@ Delete a message. The current user must be the same user who created the Message ## Retrieve the Messages in a Channel -Retrieve a stream of the Messages in a channel. This endpoint responds to [pagination parameters](/docs/resources/post/#general-parameters). +Retrieve a stream of the Messages in a channel. + +<%= general_params_note_for "message" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope'] %> diff --git a/content/docs/resources/message/lookup.md b/content/docs/resources/message/lookup.md index 0c6cfd6..e6dc706 100644 --- a/content/docs/resources/message/lookup.md +++ b/content/docs/resources/message/lookup.md @@ -13,6 +13,8 @@ Returns a specific [Message](/docs/resources/message/). *Note: you can always retrieve a message you created even if you are no longer able to view the rest of the Channel anymore.* +<%= general_params_note_for "message" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "channels/[channel_id]/messages/[message_id]", "User", "public_messages or messages" %> @@ -61,6 +63,8 @@ Returns a specific [Message](/docs/resources/message/). Returns multiple Messages requested by id. At most 200 messages can be requested. Messages may be requested from more than one channel at a time. Messages which do not exist or which the requesting user does not have authorization to view will not be returned. +<%= general_params_note_for "message" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "channels/messages", "User", "public_messages or messages" %> @@ -109,7 +113,11 @@ Returns multiple Messages requested by id. At most 200 messages can be requested ## Retrieve my Messages -Retrieve a stream of the Messages the current user has created. This endpoint responds to [pagination parameters](/docs/resources/post/#general-parameters). +Retrieve a stream of the Messages the current user has created. + +<%= general_params_note_for "message" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope'] %> diff --git a/content/docs/resources/post/index.md b/content/docs/resources/post/index.md index c58a88b..5aa2811 100644 --- a/content/docs/resources/post/index.md +++ b/content/docs/resources/post/index.md @@ -222,7 +222,7 @@ Some posts with annotations data may not be meant for direct consumption by a Us ## General parameters -Requests for streams of Posts respond to [pagination parameters](/docs/basics/pagination). Additionally they accept the following query string parameters: +Where noted, Post endpoints respond to the following query string parameters: @@ -291,6 +291,8 @@ Requests for streams of Posts respond to [pagination parameters](/docs/basics/pa
    +Where noted, endpoints that return a stream of Posts additionally respond to [pagination parameters](/docs/basics/pagination). + ## Sorting Posts Post `id` is the ordering field for multiple posts, not `created_at`. `created_at` is meant to be displayed to users, not to sort Posts. This also makes pagination with `since_id` and `before_id` more straightforward. Posts are presently always returned in reverse chronological order (newest to oldest). As a result, the Posts endpoints will always return the newest posts that meet the requested criteria (e.g. `before_id` and `count`). diff --git a/content/docs/resources/post/lifecycle.md b/content/docs/resources/post/lifecycle.md index c790aa5..dd653f3 100644 --- a/content/docs/resources/post/lifecycle.md +++ b/content/docs/resources/post/lifecycle.md @@ -17,6 +17,8 @@ If you want to test how your text will be processed you can use the [text proces *Note: You cannot reply to a repost. Please reply to the parent Post.* +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "posts", "User", "write_post" %> @@ -143,6 +145,8 @@ If you want to test how your text will be processed you can use the [text proces Delete a Post. The current user must be the same user who created the Post. It returns the deleted Post on success. +<%= general_params_note_for "post" %> + *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* <%= migration_warning ['response_envelope'] %> diff --git a/content/docs/resources/post/lookup.md b/content/docs/resources/post/lookup.md index f519519..d5a5484 100644 --- a/content/docs/resources/post/lookup.md +++ b/content/docs/resources/post/lookup.md @@ -11,6 +11,8 @@ title: "Post Lookup" Returns a specific [Post](/docs/resources/post/). +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts/[post_id]", "None" %> @@ -76,6 +78,8 @@ Returns a specific [Post](/docs/resources/post/). Returns multiple Posts requested by id. At most 200 posts can be requested. +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts", "Any" %> diff --git a/content/docs/resources/post/replies.md b/content/docs/resources/post/replies.md index 844ac19..9ba73dd 100644 --- a/content/docs/resources/post/replies.md +++ b/content/docs/resources/post/replies.md @@ -13,6 +13,10 @@ Retrieve all the [Posts](/docs/resources/post/) that are in the same thread as t **This endpoint would be more accurately named ```stream/0/posts/{post_id}/thread``` and may be renamed in a later API version.** +<%= general_params_note_for "post" %> + +<%= pagination_note %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts/[post_id]/replies", "Any" %> @@ -21,8 +25,6 @@ Retrieve all the [Posts](/docs/resources/post/) that are in the same thread as t ["post_id","The id of a Post in the thread to retrieve."] ]%> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* - #### Example > GET https://alpha-api.app.net/stream/0/posts/1/replies diff --git a/content/docs/resources/post/report.md b/content/docs/resources/post/report.md index d6a1409..b6434c8 100644 --- a/content/docs/resources/post/report.md +++ b/content/docs/resources/post/report.md @@ -13,6 +13,8 @@ Report a post as spam. This will mute the author of the post and send a report t > If you are testing this endpoint, please send an email to [support@app.net](mailto:support@app.net) letting us know the account you are about to report. +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "posts/[post_id]/report", "User" %> diff --git a/content/docs/resources/post/reposts.md b/content/docs/resources/post/reposts.md index 727ac33..60f8806 100644 --- a/content/docs/resources/post/reposts.md +++ b/content/docs/resources/post/reposts.md @@ -17,6 +17,8 @@ For compatibility with clients who don't wish to show reposts specially, we set - Reposts do not show up in the hashtags, mentions or global streams. - A repost of Post A will only show up in a User's stream if they have not seen Post A (or another repost of Post A) in a reasonable amount of time (currently 1 week). +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "posts/[post_id]/repost", "User", "write_post" %> @@ -100,6 +102,8 @@ For compatibility with clients who don't wish to show reposts specially, we set Given the original ```post_id```, delete the current user's repost. *Note: this same functionality can be accomplished by [deleting using the repost's post_id](/docs/resources/post/lifecycle/#delete-a-post)*. +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "DELETE", "posts/[post_id]/repost", "User", "write_post" %> diff --git a/content/docs/resources/post/stars.md b/content/docs/resources/post/stars.md index 838325e..fc32261 100644 --- a/content/docs/resources/post/stars.md +++ b/content/docs/resources/post/stars.md @@ -13,6 +13,8 @@ Save a given Post to the current User's stars. This is just a "save" action, not *Note: A repost cannot be starred. Please star the parent Post.* +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "posts/[post_id]/star", "User", "write_post" %> @@ -78,6 +80,8 @@ Save a given Post to the current User's stars. This is just a "save" action, not Remove a Star from a Post. +<%= general_params_note_for "post" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "DELETE", "posts/[post_id]/star", "User", "write_post" %> @@ -143,6 +147,10 @@ Remove a Star from a Post. Get the most recent [Posts](/docs/resources/post/) starred by a specific [User](/docs/resources/user/) in reverse post order. Stars are a way for Users to save posts without rebroadcasting the Post to their followers. +<%= general_params_note_for "post" %> + +<%= pagination_note %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/[user_id]/stars", "None" %> diff --git a/content/docs/resources/post/streams.md b/content/docs/resources/post/streams.md index b8614a4..546ec01 100644 --- a/content/docs/resources/post/streams.md +++ b/content/docs/resources/post/streams.md @@ -11,13 +11,13 @@ title: "Post Streams" Return the 20 most recent [Posts](/docs/resources/post/) from the Global stream. -<%= migration_warning ['response_envelope'] %> +<%= general_params_note_for "post" %> -<%= endpoint "GET", "posts/stream/global", "None" %> +<%= pagination_note %> -#### Parameters +<%= migration_warning ['response_envelope'] %> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* +<%= endpoint "GET", "posts/stream/global", "None" %> #### Example @@ -82,7 +82,9 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the Global stream. Get the most recent [Posts](/docs/resources/post/) created by a specific [User](/docs/resources/user/) in reverse post order. -*Note: the User object is not returned for these Posts.* +<%= general_params_note_for "post" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope'] %> @@ -92,8 +94,6 @@ Get the most recent [Posts](/docs/resources/post/) created by a specific [User]( ["user_id", "The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] ]%> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* - #### Example > GET https://alpha-api.app.net/stream/0/users/1/posts @@ -157,6 +157,10 @@ Get the most recent [Posts](/docs/resources/post/) created by a specific [User]( Get the most recent [Posts](/docs/resources/post/) mentioning by a specific [User](/docs/resources/user/) in reverse post order. +<%= general_params_note_for "post" %> + +<%= pagination_note %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/[user_id]/mentions", "Any" %> @@ -165,8 +169,6 @@ Get the most recent [Posts](/docs/resources/post/) mentioning by a specific [Use ["user_id", "The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] ]%> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* - #### Example > GET https://alpha-api.app.net/stream/0/users/2/mentions @@ -230,13 +232,13 @@ Get the most recent [Posts](/docs/resources/post/) mentioning by a specific [Use Return the 20 most recent [Posts](/docs/resources/post/) from the current User and the Users they follow. -<%= migration_warning ['response_envelope'] %> +<%= general_params_note_for "post" %> -<%= endpoint "GET", "posts/stream", "User", "stream" %> +<%= pagination_note %> -#### Parameters +<%= migration_warning ['response_envelope'] %> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* +<%= endpoint "GET", "posts/stream", "User", "stream" %> #### Example @@ -301,13 +303,13 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current User a Return the 20 most recent [Posts](/docs/resources/post/) from the current user's [personalized stream](#retrieve-a-users-personalized-stream) and [mentions stream](#retrieve-posts-mentioning-a-user) merged into one stream. -<%= migration_warning ['response_envelope'] %> +<%= general_params_note_for "post" %> -<%= endpoint "GET", "posts/stream/unified", "User", "stream" %> +<%= pagination_note %> -#### Parameters +<%= migration_warning ['response_envelope'] %> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* +<%= endpoint "GET", "posts/stream/unified", "User", "stream" %> #### Example @@ -372,13 +374,13 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current user's Return the 20 most recent [Posts](/docs/resources/post/) for a specific hashtag. -<%= migration_warning ['response_envelope'] %> +<%= general_params_note_for "post" %> -<%= endpoint "GET", "posts/tag/[hashtag]", "None" %> +<%= pagination_note %> -#### Parameters +<%= migration_warning ['response_envelope'] %> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* +<%= endpoint "GET", "posts/tag/[hashtag]", "None" %> #### Example diff --git a/content/docs/resources/token/index.md b/content/docs/resources/token/index.md index bc9eabf..53079dd 100644 --- a/content/docs/resources/token/index.md +++ b/content/docs/resources/token/index.md @@ -156,12 +156,12 @@ Returns a list of ids of Users that have authorized an app. Must be requested us Returns a list of User tokens corresponding to an app token. Must be requested using an [app access token](/docs/authentication/#access-tokens). +<%= pagination_note %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "apps/me/tokens", "App" %> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* - #### Example > GET https://alpha-api.app.net/stream/0/apps/me/tokens diff --git a/content/docs/resources/user/blocking.md b/content/docs/resources/user/blocking.md index a57ca4b..8ee4425 100644 --- a/content/docs/resources/user/blocking.md +++ b/content/docs/resources/user/blocking.md @@ -13,6 +13,8 @@ Block a user from seeing your App.net content. This means the user will not be a In most cases, [muting a user](/docs/resources/user/muting/#mute-a-user) is probably sufficient since that hides all of a user's content from you. If a user is aggressively reposting or starring your content, blocking them will prevent them from interacting with your content at all. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "users/[user_id]/block", "User", "follow" %> @@ -91,6 +93,8 @@ In most cases, [muting a user](/docs/resources/user/muting/#mute-a-user) is prob Allow a blocked user to interact with my content. +<%= general_params_note_for "user" %> + *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* <%= migration_warning ['response_envelope'] %> @@ -171,6 +175,8 @@ Allow a blocked user to interact with my content. Retrieve a list of blocked users. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/[user_id]/blocked", "Any" %> diff --git a/content/docs/resources/user/following.md b/content/docs/resources/user/following.md index b9b133b..030220a 100644 --- a/content/docs/resources/user/following.md +++ b/content/docs/resources/user/following.md @@ -11,6 +11,8 @@ title: "User Following" Returns the User object of the user being followed. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "users/[user_id]/follow", "User", "follow" %> @@ -88,6 +90,8 @@ Returns the User object of the user being fo Returns the User object of the user being unfollowed. +<%= general_params_note_for "user" %> + *Remember, access tokens cannot be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* <%= migration_warning ['response_envelope'] %> @@ -165,7 +169,11 @@ Returns the User object of the user being un ## List users a user is following -Returns a list of User objects the specified user is following. Please note that the pagination is not based on user or post ids. +Returns a list of User objects the specified user is following. + +<%= general_params_note_for "user" %> + +<%= pagination_note %> <%= migration_warning ['response_envelope','follow_pagination'] %> @@ -250,6 +258,10 @@ Returns a list of User objects the specified Returns a list of User objects for users following the specified user. Please note that the pagination is not based on user or post ids. +<%= general_params_note_for "user" %> + +<%= pagination_note %> + <%= migration_warning ['response_envelope','follow_pagination'] %> <%= endpoint "GET", "users/[user_id]/followers", "Any" %> diff --git a/content/docs/resources/user/index.md b/content/docs/resources/user/index.md index 4325d56..04d2ac5 100644 --- a/content/docs/resources/user/index.md +++ b/content/docs/resources/user/index.md @@ -253,7 +253,7 @@ A user's avatar and cover images can be [directly requested](/docs/resources/use ## General parameters -Requests that return streams of Users respond to [pagination parameters](/docs/basics/pagination). Additionally they accept the following query string parameters: +Where noted, User endpoints respond to the following query string parameters: @@ -280,4 +280,6 @@ Requests that return streams of Users respond to [pagination parameters](/docs/b
    +Where noted, endpoints that return a stream of Users additionally respond to [pagination parameters](/docs/basics/pagination). + <%= render 'partials/endpoints-tab', :for => "user" %> diff --git a/content/docs/resources/user/lookup.md b/content/docs/resources/user/lookup.md index 76f5bc9..4a90bda 100644 --- a/content/docs/resources/user/lookup.md +++ b/content/docs/resources/user/lookup.md @@ -11,6 +11,8 @@ title: "User Lookup" Returns a specific User object. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/[user_id]", "None" %> @@ -87,6 +89,8 @@ Returns a specific User object. ## Retrieve multiple Users Returns multiple Users requested by id. At most 200 users can be requested. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users", "Any" %> @@ -125,6 +129,8 @@ Returns multiple Users requested by id. At most 200 users can be requested. Search the App.net userbase. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/search", "Any" %> diff --git a/content/docs/resources/user/muting.md b/content/docs/resources/user/muting.md index 817d4df..7fd9fbe 100644 --- a/content/docs/resources/user/muting.md +++ b/content/docs/resources/user/muting.md @@ -9,7 +9,9 @@ title: "User Muting" ## Mute a User -Hide all posts for a User in all streams. *Note: if you still explicitly request a this User's stream or a Post from this user, it will not be hidden.* +Hide all posts for a User in all streams. *Note: if you still explicitly request this User's stream or a Post from this User, it will not be hidden.* + +<%= general_params_note_for "user" %> <%= migration_warning ['response_envelope'] %> @@ -88,6 +90,8 @@ Hide all posts for a User in all streams. *Note: if you still explicitly request Stop hiding all posts for a given user. +<%= general_params_note_for "user" %> + *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* <%= migration_warning ['response_envelope'] %> @@ -167,6 +171,8 @@ Stop hiding all posts for a given user. Retrieve a list of muted users. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "users/[user_id]/muted", "Any" %> diff --git a/content/docs/resources/user/post-interactions.md b/content/docs/resources/user/post-interactions.md index d4c5d53..cb11224 100644 --- a/content/docs/resources/user/post-interactions.md +++ b/content/docs/resources/user/post-interactions.md @@ -11,6 +11,8 @@ title: "User Post Interactions" List all the Users who have reposted a given Post. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts/[post_id]/reposters", "Any" %> @@ -91,6 +93,8 @@ List all the Users who have reposted a given Post. List all the Users who have starred a given Post. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "GET", "posts/[post_id]/stars", "Any" %> diff --git a/content/docs/resources/user/profile.md b/content/docs/resources/user/profile.md index e8d8fbf..933360e 100644 --- a/content/docs/resources/user/profile.md +++ b/content/docs/resources/user/profile.md @@ -13,6 +13,8 @@ Updates a specific user's profile details. You can update a user by PUTing an ob If you want to add or update a User's annotations, you may include the optional ```annotations``` key and pass in the annotations that are changing. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "PUT", "users/me", "User", "update_profile" %> @@ -91,6 +93,7 @@ Retrieve a User's avatar image. This endpoint does not require authentication, i Replace a User's avatar image with the uploaded file. The uploaded image Will be cropped to square and must be smaller than 1 MB. The optimal size for this image is 200×200 pixels. The content type for this request must be ```multipart/form-data```. + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "users/me/avatar", "User", "update_profile" %> @@ -202,6 +205,8 @@ Retrieve a User's cover image. This endpoint does not require authentication, is Replace a User's cover image with the uploaded file. The uploaded image must be at least 960px wide and less than 4 MB in size. The content type for this request must be ```multipart/form-data```. +<%= general_params_note_for "user" %> + <%= migration_warning ['response_envelope'] %> <%= endpoint "POST", "users/me/cover", "User", "update_profile" %> diff --git a/lib/helpers.rb b/lib/helpers.rb index c9529a6..9147d81 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -39,5 +39,13 @@ def post_params(params = []) end def file_token_reminder() - "
    Please see the File Authorization documentation for more information on User and File tokens.
    " + "
    Please see the File Authorization documentation for more information on User and File tokens.
    " +end + +def pagination_note() + 'Responses from this endpoint are paginated.' +end + +def general_params_note_for(type) + 'This endpoint responds to general '+type.capitalize+' parameters.' end \ No newline at end of file From abe0b237feafd7a3ebf13ca0ea49cb2219b905dc Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Fri, 29 Mar 2013 14:55:52 -0700 Subject: [PATCH 023/231] Add some character limits --- content/docs/resources/file/index.md | 2 +- content/docs/resources/post/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/resources/file/index.md b/content/docs/resources/file/index.md index f63c9f0..ac6f23f 100644 --- a/content/docs/resources/file/index.md +++ b/content/docs/resources/file/index.md @@ -97,7 +97,7 @@ A file uploaded by a User and hosted by App.net. name string - The user provided name of the File. + The user provided name of the File. All Unicode characters allowed. Maximum length 255 characters. public diff --git a/content/docs/resources/post/index.md b/content/docs/resources/post/index.md index 5aa2811..8c90fac 100644 --- a/content/docs/resources/post/index.md +++ b/content/docs/resources/post/index.md @@ -97,7 +97,7 @@ A Post is the other central object utilized by the App.net Stream API. It has ri text string - User supplied text of the post. + User supplied text of the post. All Unicode characters allowed. Maximum length 256 characters. html From f2e5c259afea2171f47ce370b952cbdf92c2a2a8 Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Mon, 1 Apr 2013 19:40:21 -0700 Subject: [PATCH 024/231] Clean up --- content/docs/basics/pagination.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/content/docs/basics/pagination.md b/content/docs/basics/pagination.md index b139606..b795f9d 100644 --- a/content/docs/basics/pagination.md +++ b/content/docs/basics/pagination.md @@ -34,34 +34,26 @@ In summary: ## Parameters -Requests for paginated streams can be filtered by passing the following query string parameters along with the request: +Requests for paginated streams can optionally be filtered by passing the following query string parameters along with the request: - - - - - + - - - + - - From 22bfefce93679de090fb8300fdb7677479a8d22e Mon Sep 17 00:00:00 2001 From: Orian Marx Date: Mon, 1 Apr 2013 19:41:17 -0700 Subject: [PATCH 025/231] Add count parameter --- content/docs/resources/user/lookup.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/docs/resources/user/lookup.md b/content/docs/resources/user/lookup.md index 4a90bda..5768c66 100644 --- a/content/docs/resources/user/lookup.md +++ b/content/docs/resources/user/lookup.md @@ -136,7 +136,8 @@ Search the App.net userbase. <%= endpoint "GET", "users/search", "Any" %> <%= query_params [ - ["q","The search query. Supports @username or #tag searches as well as normal search terms. Searches username, display name, bio information. Does not search posts."] + ["q","The search query. Supports @username or #tag searches as well as normal search terms. Searches username, display name, bio information. Does not search posts."], + ["count","(Optional) The number of Users to return, up to a maximum of 200. Defaults to 20 if not specified."] ]%> #### Example From 321bfafd0dfdd49e573c718cf369718a4b5f31dd Mon Sep 17 00:00:00 2001 From: Roberto Maisl Date: Fri, 5 Apr 2013 11:33:34 +0200 Subject: [PATCH 026/231] Fix inclusion of File endpoints in overall listing of endpoints A tiny typo caused the Filter endpoints being included instead. --- content/docs/resources/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/index.md b/content/docs/resources/index.md index 0401815..8610fab 100644 --- a/content/docs/resources/index.md +++ b/content/docs/resources/index.md @@ -38,7 +38,7 @@ Please use https://alpha-api.app.net/ to access the APIs. ## File -<%= render 'partials/endpoints/filter' %> +<%= render 'partials/endpoints/file' %> ## Stream From 6e0b77e8c6da6fbc209a5fabbeb75ec067b4ee05 Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Sat, 6 Apr 2013 20:23:34 -0700 Subject: [PATCH 027/231] Update contact info --- content/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/index.md b/content/index.md index 550da80..01d6a07 100644 --- a/content/index.md +++ b/content/index.md @@ -24,7 +24,7 @@ To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adna ### Getting help and providing feedback -There are numerous ways for developers to get help utilizing the platform and to provide feedback. During typical San Francisco business hours there are App.net staff members available to answer questions in our [HipChat](http://www.hipchat.com/garqCaGOZ). Developers (along with App.net staff) are often chatting in the [Developer Channel](http://patter-app.net/room.html?channel=1383). For general inquiries about account/service related issues email [support@app.net](mailto:support@app.net). For developer inquiries about the API, our Terms of Service, letting us know about something you're working on, etc., email [developers@app.net](mailto:developers@app.net). In addition to the above you can report bugs and provide feedback on the API using the [issue tracker](https://github.com/appdotnet/api-spec/issues) or by using pull requests and commit comments on the [Github repo for the API](https://github.com/appdotnet/api-spec/) or the repo for these docs. You can also contact our Developer Advocate [@orian](http://alpha.app.net/orian). +There are numerous ways for developers to get help utilizing the platform and to provide feedback. During typical San Francisco business hours there are App.net staff members available to answer questions in our [HipChat](http://www.hipchat.com/garqCaGOZ). Developers (along with App.net staff) are often chatting in the [Developer Channel](http://patter-app.net/room.html?channel=1383). For general inquiries about account/service related issues email [support@app.net](mailto:support@app.net). For developer inquiries about the API, our Terms of Service, letting us know about something you're working on, etc., email [developers@app.net](mailto:developers@app.net). In addition to the above you can report bugs and provide feedback on the API using the [issue tracker](https://github.com/appdotnet/api-spec/issues) or by using pull requests and commit comments on the [Github repo for the API](https://github.com/appdotnet/api-spec/) or the repo for these docs. ### Terms of Service @@ -54,7 +54,6 @@ Libraries, tools, code samples, blog posts and other resources to help you build #### Your hosts * [Bryan Berg](http://ber.gd) ([@berg](https://alpha.app.net/berg), [bryan@app.net](mailto:bryan@app.net)) -* [Orian Marx](http://orianmarx.com) ([@orian](https://alpha.app.net/orian), [orian@app.net](mailto:orian@app.net)) * Mark Thurman ([@mthurman](https://alpha.app.net/mthurman), [mthurman@app.net](mthurman@app.net)) * [Alex Kessinger](http://alexkessinger.net) ([@voidfiles](https://alpha.app.net/voidfiles), [alex@app.net](mailto:alex@app.net)) * Brian Armstrong ([@barmstrong](https://alpha.app.net/barmstrong), [barmstrong@app.net](mailto:barmstrong@app.net)) From 22553bef5b7dec1beda7ba617f96e5f39f20885e Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Sat, 6 Apr 2013 21:53:01 -0700 Subject: [PATCH 028/231] update nanoc etc --- Gemfile | 3 ++- lib/static.rb | 55 --------------------------------------------------- 2 files changed, 2 insertions(+), 56 deletions(-) delete mode 100644 lib/static.rb diff --git a/Gemfile b/Gemfile index 6cc860b..6b5b3e5 100644 --- a/Gemfile +++ b/Gemfile @@ -6,4 +6,5 @@ gem 'fssm' gem 'kramdown' gem 'coderay' gem 'pygments.rb' -gem 'nokogiri' \ No newline at end of file +gem 'nokogiri' + diff --git a/lib/static.rb b/lib/static.rb deleted file mode 100644 index 5fc243c..0000000 --- a/lib/static.rb +++ /dev/null @@ -1,55 +0,0 @@ -require 'digest/sha1' - -module Nanoc3::DataSources - - class Static < Nanoc3::DataSource - - identifier :static - - def items - # Get prefix - prefix = config[:prefix] || 'static' - - # Get all files under prefix dir - filenames = Dir[prefix + '/**/*'].select { |f| File.file?(f) } - - # Convert filenames to items - filenames.map do |filename| - attributes = { - :extension => File.extname(filename)[1..-1], - :filename => filename, - } - identifier = filename[(prefix.length+1)..-1] + '/' - - mtime = File.mtime(filename) - checksum = checksum_for(filename) - - Nanoc3::Item.new( - filename, - attributes, - identifier, - :binary => true, :mtime => mtime, :checksum => checksum - ) - end - end - - private - - # Returns a checksum of the given filenames - # TODO un-duplicate this somewhere - def checksum_for(*filenames) - filenames.flatten.map do |filename| - digest = Digest::SHA1.new - File.open(filename, 'r') do |io| - until io.eof - data = io.readpartial(2**10) - digest.update(data) - end - end - digest.hexdigest - end.join('-') - end - - end - -end \ No newline at end of file From b39192575ee501cca02cc99aa6f628f53c488568 Mon Sep 17 00:00:00 2001 From: Derek Shockey Date: Sun, 7 Apr 2013 12:05:13 -0700 Subject: [PATCH 029/231] user ID should be a string --- content/docs/resources/channel/lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/channel/lifecycle.md b/content/docs/resources/channel/lifecycle.md index e37fbda..eb49edf 100644 --- a/content/docs/resources/channel/lifecycle.md +++ b/content/docs/resources/channel/lifecycle.md @@ -29,7 +29,7 @@ Send a JSON document that matches the [Channel schema](/docs/resources/channel/) > > Content-Type: application/json > -> DATA {"type": "com.example.channel", "writers": {"user_ids": ["@berg", 1]}} +> DATA {"type": "com.example.channel", "writers": {"user_ids": ["@berg", "1"]}} ~~~ js { From af7c34a68ca00294e5fa9a44eae515352b0fae26 Mon Sep 17 00:00:00 2001 From: Andrew Knapp Date: Wed, 10 Apr 2013 15:22:04 -0700 Subject: [PATCH 030/231] Clean up the Gemfile - Make sure we get gems from https - List all dependencies and versions in the gemfile - Update .gitignore to allow for the use of bundler --- .gitignore | 3 +++ Gemfile | 21 +++++++++++++-------- 2 files changed, 16 insertions(+), 8 deletions(-) diff --git a/.gitignore b/.gitignore index 1bbe05e..da9665c 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,6 @@ output tmp crash.log Gemfile.lock +bin +vendor +.bundle diff --git a/Gemfile b/Gemfile index 6b5b3e5..102919f 100644 --- a/Gemfile +++ b/Gemfile @@ -1,10 +1,15 @@ -source "http://rubygems.org/" +source "https://rubygems.org/" -gem 'nanoc' -gem 'adsf' -gem 'fssm' -gem 'kramdown' -gem 'coderay' -gem 'pygments.rb' -gem 'nokogiri' +gem 'nanoc', '3.6.2' +gem 'adsf', '1.1.1' +gem 'fssm', '0.2.10' +gem 'kramdown', '1.0.1' +gem 'coderay', '1.0.9' +gem 'pygments.rb', '0.4.2' +gem 'nokogiri', '1.5.9' +gem 'rack', '1.5.2' +gem 'colored', '1.2' +gem 'cri', '2.3.0' +gem 'posix-spawn', '0.3.6' +gem 'yajl-ruby', '1.1.0' From d13d936c0f388ee3f2943b6feca097930522cfc7 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 10 Apr 2013 15:39:24 -0700 Subject: [PATCH 031/231] Update docs to use adn_base styles --- config.yaml | 8 +++ config/production.yml | 89 ++++++++++++++++++++++++++++++ config/sandbox.yaml | 89 ++++++++++++++++++++++++++++++ content/docs/basics/migrations.md | 2 +- content/docs/basics/pagination.md | 6 +- content/docs/basics/rate-limits.md | 4 +- content/docs/basics/responses.md | 2 +- content/docs/meta/annotations.md | 2 +- content/docs/meta/entities.md | 2 +- layouts/default.html | 72 +++++++++++++++--------- static/css/style.css | 52 +++++++++++++++++ 11 files changed, 292 insertions(+), 36 deletions(-) create mode 100644 config/production.yml create mode 100644 config/sandbox.yaml diff --git a/config.yaml b/config.yaml index 4a8a7a8..26b52fd 100644 --- a/config.yaml +++ b/config.yaml @@ -1,3 +1,8 @@ +# Nanoc really doesn't have any sense of an environment +# Instead we have a different config file for each enviroment +# If you make a change to one config file, you need to make a change to all of them + + # A list of file extensions that nanoc will consider to be textual rather than # binary. If an item with an extension not in this list is found, the file # will be considered as binary. @@ -79,3 +84,6 @@ watcher: # When to send notifications (using Growl or notify-send). notify_on_compilation_success: true notify_on_compilation_failure: true + +local_hostname: "localhost" +lanai_hostname: "sandbox.app.net" diff --git a/config/production.yml b/config/production.yml new file mode 100644 index 0000000..7adc800 --- /dev/null +++ b/config/production.yml @@ -0,0 +1,89 @@ +# Nanoc really doesn't have any sense of an environment +# Instead we have a different config file for each enviroment +# If you make a change to one config file, you need to make a change to all of them + + +# A list of file extensions that nanoc will consider to be textual rather than +# binary. If an item with an extension not in this list is found, the file +# will be considered as binary. +text_extensions: [ 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'ms', 'mustache', 'php', 'rb', 'sass', 'scss', 'txt', 'xhtml', 'xml' ] + +# The path to the directory where all generated files will be written to. This +# can be an absolute path starting with a slash, but it can also be path +# relative to the site directory. +output_dir: output_production + +# A list of index filenames, i.e. names of files that will be served by a web +# server when a directory is requested. Usually, index files are named +# “index.html”, but depending on the web server, this may be something else, +# such as “default.htm”. This list is used by nanoc to generate pretty URLs. +index_filenames: [ 'index.html' ] + +# Whether or not to generate a diff of the compiled content when compiling a +# site. The diff will contain the differences between the compiled content +# before and after the last site compilation. +enable_output_diff: false + +prune: + # Whether to automatically remove files not managed by nanoc from the output + # directory. For safety reasons, this is turned off by default. + auto_prune: false + + # Which files and directories you want to exclude from pruning. If you version + # your output directory, you should probably exclude VCS directories such as + # .git, .svn etc. + exclude: [ '.git', '.hg', '.svn', 'CVS' ] + +# The data sources where nanoc loads its data from. This is an array of +# hashes; each array element represents a single data source. By default, +# there is only a single data source that reads data from the “content/” and +# “layout/” directories in the site directory. +data_sources: + - + # The type is the identifier of the data source. By default, this will be + # `filesystem_unified`. + type: filesystem_unified + + # The path where items should be mounted (comparable to mount points in + # Unix-like systems). This is “/” by default, meaning that items will have + # “/” prefixed to their identifiers. If the items root were “/en/” + # instead, an item at content/about.html would have an identifier of + # “/en/about/” instead of just “/about/”. + items_root: / + + # The path where layouts should be mounted. The layouts root behaves the + # same as the items root, but applies to layouts rather than items. + layouts_root: / + + # Whether to allow periods in identifiers. When turned off, everything + # past the first period is considered to be the extension, and when + # turned on, only the characters past the last period are considered to + # be the extension. For example, a file named “content/about.html.erb” + # will have the identifier “/about/” when turned off, but when turned on + # it will become “/about.html/” instead. + allow_periods_in_identifiers: false + + - + type: static + items_root: /static + +# Configuration for the “watch” command, which watches a site for changes and +# recompiles if necessary. +watcher: + # A list of directories to watch for changes. When editing this, make sure + # that the “output/” and “tmp/” directories are _not_ included in this list, + # because recompiling the site will cause these directories to change, which + # will cause the site to be recompiled, which will cause these directories + # to change, which will cause the site to be recompiled again, and so on. + dirs_to_watch: [ 'content', 'layouts', 'lib' ] + + # A list of single files to watch for changes. As mentioned above, don’t put + # any files from the “output/” or “tmp/” directories in here. + files_to_watch: [ 'config.yaml', 'Rules' ] + + # When to send notifications (using Growl or notify-send). + notify_on_compilation_success: true + notify_on_compilation_failure: true + +local_hostname: "developers.app.net" +lanai_hostname: "account.app.net" diff --git a/config/sandbox.yaml b/config/sandbox.yaml new file mode 100644 index 0000000..9a2eb88 --- /dev/null +++ b/config/sandbox.yaml @@ -0,0 +1,89 @@ +# Nanoc really doesn't have any sense of an environment +# Instead we have a different config file for each enviroment +# If you make a change to one config file, you need to make a change to all of them + + +# A list of file extensions that nanoc will consider to be textual rather than +# binary. If an item with an extension not in this list is found, the file +# will be considered as binary. +text_extensions: [ 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'ms', 'mustache', 'php', 'rb', 'sass', 'scss', 'txt', 'xhtml', 'xml' ] + +# The path to the directory where all generated files will be written to. This +# can be an absolute path starting with a slash, but it can also be path +# relative to the site directory. +output_dir: output_sandbox + +# A list of index filenames, i.e. names of files that will be served by a web +# server when a directory is requested. Usually, index files are named +# “index.html”, but depending on the web server, this may be something else, +# such as “default.htm”. This list is used by nanoc to generate pretty URLs. +index_filenames: [ 'index.html' ] + +# Whether or not to generate a diff of the compiled content when compiling a +# site. The diff will contain the differences between the compiled content +# before and after the last site compilation. +enable_output_diff: false + +prune: + # Whether to automatically remove files not managed by nanoc from the output + # directory. For safety reasons, this is turned off by default. + auto_prune: false + + # Which files and directories you want to exclude from pruning. If you version + # your output directory, you should probably exclude VCS directories such as + # .git, .svn etc. + exclude: [ '.git', '.hg', '.svn', 'CVS' ] + +# The data sources where nanoc loads its data from. This is an array of +# hashes; each array element represents a single data source. By default, +# there is only a single data source that reads data from the “content/” and +# “layout/” directories in the site directory. +data_sources: + - + # The type is the identifier of the data source. By default, this will be + # `filesystem_unified`. + type: filesystem_unified + + # The path where items should be mounted (comparable to mount points in + # Unix-like systems). This is “/” by default, meaning that items will have + # “/” prefixed to their identifiers. If the items root were “/en/” + # instead, an item at content/about.html would have an identifier of + # “/en/about/” instead of just “/about/”. + items_root: / + + # The path where layouts should be mounted. The layouts root behaves the + # same as the items root, but applies to layouts rather than items. + layouts_root: / + + # Whether to allow periods in identifiers. When turned off, everything + # past the first period is considered to be the extension, and when + # turned on, only the characters past the last period are considered to + # be the extension. For example, a file named “content/about.html.erb” + # will have the identifier “/about/” when turned off, but when turned on + # it will become “/about.html/” instead. + allow_periods_in_identifiers: false + + - + type: static + items_root: /static + +# Configuration for the “watch” command, which watches a site for changes and +# recompiles if necessary. +watcher: + # A list of directories to watch for changes. When editing this, make sure + # that the “output/” and “tmp/” directories are _not_ included in this list, + # because recompiling the site will cause these directories to change, which + # will cause the site to be recompiled, which will cause these directories + # to change, which will cause the site to be recompiled again, and so on. + dirs_to_watch: [ 'content', 'layouts', 'lib' ] + + # A list of single files to watch for changes. As mentioned above, don’t put + # any files from the “output/” or “tmp/” directories in here. + files_to_watch: [ 'config.yaml', 'Rules' ] + + # When to send notifications (using Growl or notify-send). + notify_on_compilation_success: true + notify_on_compilation_failure: true + +local_hostname: "developers.mxmlabs.com" +lanai_hostname: "account.sandbox.app.net" diff --git a/content/docs/basics/migrations.md b/content/docs/basics/migrations.md index 2b6ace0..12e1830 100644 --- a/content/docs/basics/migrations.md +++ b/content/docs/basics/migrations.md @@ -37,7 +37,7 @@ For JSONP requests we offer the ability to override the default migration behavi ## Current Migrations -
    NameRequired?Type Description
    since_idOptionalstringReturn objects following the max_id provided in the response metadata of a previous query or one of the special pagination ids for streams with Stream Markers.Return objects following the max_id provided in the response metadata of a previous query or following one of the special pagination ids for streams with Stream Markers.
    before_idOptionalstringReturn objects preceding the min_id provided in the response metadata of a previous query or one of the special pagination ids for streams with Stream Markers.Return objects preceding the min_id provided in the response metadata of a previous query or preceding one of the special pagination ids for streams with Stream Markers.
    countOptionalinteger The number of objects to return, up to a maximum of 200. If this value is negative, items will be returned starting at since_id. Please see the pagination overview for more information.
    +
    diff --git a/content/docs/basics/pagination.md b/content/docs/basics/pagination.md index b795f9d..ee3290a 100644 --- a/content/docs/basics/pagination.md +++ b/content/docs/basics/pagination.md @@ -36,7 +36,7 @@ In summary: Requests for paginated streams can optionally be filtered by passing the following query string parameters along with the request: -
    Key
    +
    @@ -63,7 +63,7 @@ Requests for paginated streams can optionally be filtered by passing the followi When requesting objects from an endpoint that supports [Stream Markers](/docs/resources/stream-marker), you can pass the following special values to the `since_id` and `before_id` pagination parameters: -
    Name
    +
    @@ -94,7 +94,7 @@ When requesting objects from an endpoint that supports [Stream Markers](/docs/re Responses from paginated streams will include the following fields in the `meta` object of the [response envelope](/docs/basics/responses/#response-envelope). -
    Value
    +
    diff --git a/content/docs/basics/rate-limits.md b/content/docs/basics/rate-limits.md index b9610b4..c8e9b88 100644 --- a/content/docs/basics/rate-limits.md +++ b/content/docs/basics/rate-limits.md @@ -33,7 +33,7 @@ At present, these are the limit values we use: ### Authenticated Requests (per token) -
    Name
    +
    @@ -60,7 +60,7 @@ At present, these are the limit values we use: ### Unauthenticated Requests (per IP address) -
    Type
    +
    diff --git a/content/docs/basics/responses.md b/content/docs/basics/responses.md index 6bb79d4..acab9bc 100644 --- a/content/docs/basics/responses.md +++ b/content/docs/basics/responses.md @@ -78,7 +78,7 @@ If the request was unsuccessful for some reason, no ```data``` key will be retur #### Error Slugs -
    Type
    +
    diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index e4c5095..4993508 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -32,7 +32,7 @@ In general, annotations are a list of objects that have a ```type``` and a ```va ] ~~~ -
    Slug
    +
    diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index 3a2d613..776e095 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -31,7 +31,7 @@ Bring another user's attention to your post. A mention starts with @ +
    Field Type
    diff --git a/layouts/default.html b/layouts/default.html index 619e9a0..01d2a51 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -5,32 +5,44 @@ <%= @item[:title] %> - App.net API Documentation - - + + - -
    -
    -
    - App.net API Documentation - View on Github + +
    + +
    +
    -
    -
    +
    +
    +
    -
    +
    <%= yield %>
    @@ -135,6 +147,12 @@ - + + diff --git a/static/css/style.css b/static/css/style.css index ba89d23..dcc36a6 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -18,4 +18,56 @@ .label-DELETE { background-color: #b94a48; +} + +ul.nav-list ul.nav-list ul.nav-list li a { + padding-left: 50px; +} + +.nav.header { + margin-bottom: 0; + border-bottom: none; +} + +.subnav-container { + border-bottom: 1px solid #dddddd; + margin-bottom: 30px; +} + +ul.nav-list { + padding: 0 0 5px 0; +} + +ul.nav-list li a { + font-size: 12px; + padding-top: 2px; + padding-bottom: 2px; +} + +html.breakpoint-phone .nav.header, html.breakpoint-tablet .nav.header { + min-width: 100%; + margin-bottom: 0; +} + + html.breakpoint-tablet .sidebar { + margin: 0 5%; + } + +html.breakpoint-tablet ul.nav-list ul.nav-list { + border-right: 0; +} + +html.breakpoint-phone .subnav-container .breadcrumb .ordering { + position: static; + width: auto; + top: 0; +} + +html.breakpoint-phone .container { + padding: 0 5px; +} + +html.breakpoint-tablet .nav-list { + margin-right: 0; + width: auto; } \ No newline at end of file From db64ccbd041215120f0478c72f5d9f51fae2dc7d Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 10 Apr 2013 15:41:52 -0700 Subject: [PATCH 032/231] Forgot a hostname --- layouts/default.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/default.html b/layouts/default.html index 01d2a51..64a69ad 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -5,7 +5,7 @@ <%= @item[:title] %> - App.net API Documentation - + From cf336594a6dda9cf8d59e542cc1c8da89bf8d952 Mon Sep 17 00:00:00 2001 From: Andrew Knapp Date: Wed, 10 Apr 2013 15:49:43 -0700 Subject: [PATCH 033/231] Rename the sandbox config file to staging --- config/{sandbox.yaml => staging.yaml} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename config/{sandbox.yaml => staging.yaml} (99%) diff --git a/config/sandbox.yaml b/config/staging.yaml similarity index 99% rename from config/sandbox.yaml rename to config/staging.yaml index 9a2eb88..bb0aa5e 100644 --- a/config/sandbox.yaml +++ b/config/staging.yaml @@ -11,7 +11,7 @@ text_extensions: [ 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'htm', 'h # The path to the directory where all generated files will be written to. This # can be an absolute path starting with a slash, but it can also be path # relative to the site directory. -output_dir: output_sandbox +output_dir: output_staging # A list of index filenames, i.e. names of files that will be served by a web # server when a directory is requested. Usually, index files are named From ec0fb115dfcc35f466e2989e9ac2387dd1a02209 Mon Sep 17 00:00:00 2001 From: Andrew Knapp Date: Wed, 10 Apr 2013 15:51:10 -0700 Subject: [PATCH 034/231] Rename production.yml -> production.yaml --- config/{production.yml => production.yaml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename config/{production.yml => production.yaml} (100%) diff --git a/config/production.yml b/config/production.yaml similarity index 100% rename from config/production.yml rename to config/production.yaml From 2ab54a968bbef68c3d9822ada24974dbcf963cdb Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 10 Apr 2013 15:59:08 -0700 Subject: [PATCH 035/231] Fixign extra apostrophe --- layouts/default.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/default.html b/layouts/default.html index 64a69ad..e478819 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -5,7 +5,7 @@ <%= @item[:title] %> - App.net API Documentation - + From d5497b1beacb247d0067a21dd68f2db21ebcd9f6 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 10 Apr 2013 18:49:38 -0700 Subject: [PATCH 036/231] Zebra tables less crazy alert colors --- content/docs/meta/entities.md | 6 +-- content/docs/resources/channel/index.md | 8 ++-- content/docs/resources/explore/index.md | 2 +- content/docs/resources/file/index.md | 8 ++-- content/docs/resources/filter/index.md | 8 ++-- content/docs/resources/interaction/index.md | 2 +- content/docs/resources/message/index.md | 4 +- content/docs/resources/place/index.md | 2 +- content/docs/resources/post/index.md | 4 +- content/docs/resources/stream-marker/index.md | 2 +- content/docs/resources/stream/index.md | 2 +- content/docs/resources/user/index.md | 8 ++-- content/docs/resources/user/profile.md | 4 +- layouts/partials/endpoint.md | 2 +- layouts/partials/endpoints/channel.md | 2 +- layouts/partials/endpoints/explore-stream.md | 2 +- layouts/partials/endpoints/file.md | 2 +- layouts/partials/endpoints/interaction.md | 2 +- layouts/partials/endpoints/message.md | 2 +- layouts/partials/endpoints/place.md | 2 +- layouts/partials/endpoints/post.md | 2 +- layouts/partials/endpoints/stream-marker.md | 2 +- layouts/partials/endpoints/stream.md | 2 +- layouts/partials/endpoints/text-processor.md | 2 +- layouts/partials/endpoints/token.md | 2 +- layouts/partials/endpoints/user.md | 2 +- layouts/partials/parameters.md | 2 +- static/css/style.css | 39 ++++++++++++++++++- 28 files changed, 82 insertions(+), 45 deletions(-) diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index 776e095..5324b9c 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -70,7 +70,7 @@ Tag a post about a specific subject. A hashtag starts with #. }] ~~~ -
    Field Type
    +
    @@ -106,7 +106,7 @@ Link to another website. }] ~~~ -
    Field Type
    +
    @@ -151,7 +151,7 @@ and the server replaces `{post_id}` with the id of the Post once it has been sav Currently, the only variables for URI templates that we define are ones that could not be known when the link is being constructed. Additionally, if you specify a variable that is not listed below, we will pass that through instead of replacing it with nothing. -
    Field Type
    +
    diff --git a/content/docs/resources/channel/index.md b/content/docs/resources/channel/index.md index 36e2b89..414e804 100644 --- a/content/docs/resources/channel/index.md +++ b/content/docs/resources/channel/index.md @@ -53,7 +53,7 @@ A Channel is a user created stream of Messages. It controls access to the messag ## Fields -
    Value
    +
    @@ -67,7 +67,7 @@ A Channel is a user created stream of Messages. It controls access to the messag - + - + - + - + - + - + - + diff --git a/layouts/redirect.html.erb b/layouts/redirect.html.erb new file mode 100644 index 0000000..ffd1285 --- /dev/null +++ b/layouts/redirect.html.erb @@ -0,0 +1,12 @@ + + + + + + <%= redirect[:title] %> + + + +

    This page has moved to <%= redirect[:url] %>.

    + + diff --git a/lib/redirector.rb b/lib/redirector.rb new file mode 100644 index 0000000..d87cc03 --- /dev/null +++ b/lib/redirector.rb @@ -0,0 +1,24 @@ +require 'erb' + +# Based on https://gist.github.com/maxim/1782458 +class Redirector + def self.generate(redirects, items) + redirect_template = ERB.new(File.read('layouts/redirect.html.erb')) + + redirects.each do |pairs| + pairs.each_pair do |url, aliases| + url = url.to_s + items.each do |item| + if item.identifier.start_with? url + new_url = item.identifier + aliases.each do |alias_url| + old_url = new_url.gsub(url, alias_url) + redirect = {:url => new_url, :title => item[:title]} + items << Nanoc3::Item.new(redirect_template.result(binding), { :redirect => true }, old_url) + end + end + end + end + end + end +end From c1a3d88359deb61960732407cb7e3eaff05a5b1b Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 17 Jun 2013 15:52:43 -0700 Subject: [PATCH 081/231] Add user streams documentation --- content/docs/resources/app-stream/index.md | 2 +- content/docs/resources/index.md | 8 +- content/docs/resources/user-stream/index.md | 185 ++++++++++++++++++ .../docs/resources/user-stream/lifecycle.md | 44 +++++ layouts/default.html | 4 + .../endpoints/{stream.md => app-stream.md} | 0 layouts/partials/endpoints/user-stream.md | 24 +++ 7 files changed, 264 insertions(+), 3 deletions(-) create mode 100644 content/docs/resources/user-stream/index.md create mode 100644 content/docs/resources/user-stream/lifecycle.md rename layouts/partials/endpoints/{stream.md => app-stream.md} (100%) create mode 100644 layouts/partials/endpoints/user-stream.md diff --git a/content/docs/resources/app-stream/index.md b/content/docs/resources/app-stream/index.md index a71c231..ac77280 100644 --- a/content/docs/resources/app-stream/index.md +++ b/content/docs/resources/app-stream/index.md @@ -742,4 +742,4 @@ A file is deleted. } ~~~ -<%= render 'partials/endpoints-tab', :for => "stream" %> +<%= render 'partials/endpoints-tab', :for => "app-stream" %> diff --git a/content/docs/resources/index.md b/content/docs/resources/index.md index 8610fab..5e0cd91 100644 --- a/content/docs/resources/index.md +++ b/content/docs/resources/index.md @@ -40,9 +40,13 @@ Please use https://alpha-api.app.net/ to access the APIs. <%= render 'partials/endpoints/file' %> -## Stream +## App Stream -<%= render 'partials/endpoints/stream' %> +<%= render 'partials/endpoints/app-stream' %> + +## User Stream + +<%= render 'partials/endpoints/user-stream' %> ## Filter diff --git a/content/docs/resources/user-stream/index.md b/content/docs/resources/user-stream/index.md new file mode 100644 index 0000000..4a03c8e --- /dev/null +++ b/content/docs/resources/user-stream/index.md @@ -0,0 +1,185 @@ +--- +title: "User Stream" +--- + +# User Stream + +<%= render 'partials/object-tab' %> + +* TOC +{:toc} + +## Overview + +A User Stream is a long-lived connection that allows an app to receive real-time updates on a user's behalf. If you would like to receive information on behalf of multiple users (or process all public App.net data), please use an [App Stream](/docs/resources/app-stream). Unlike App Streams (which must be used on a server), User Streams can be used by any App.net client. + +User Streams are not meant to be a global firehose from App.net. Rather, user streams are based on the idea of subscriptions. Essentially, your app makes normal API calls to App.net and then subscribes to future updates from that endpoint. Each User Stream is identified by a `connection_id` and has multiple subscriptions (which correspond to normal API endpoints) and are identified by `subscription_id`. + +The User Streaming API is meant to work in conjunction with the polling endpoints seamlessly. For instance, when a user launches an App.net iPhone client the client can create a user stream, poll to fill in new posts in the User's stream since their stream marker and at the same time subscribe to any new posts in the user's stream. + +Since memory and bandwidth is not unlimited, each Stream has associated limits. App.net maintains a buffer of objects to send to a client, but if that buffer fills, your Stream will be disconnected. Please ensure that you are only requesting streams of data that you can actually process. + +## Getting Started + +### Creating a User Stream + +A client opens a User Stream by making an authenticated connection to the user stream endpoint. The authentication token may be passed in headers or the query string [like the rest of the API](/docs/authentication/#making-authenticated-api-requests). + +The User Stream endpoint is `stream-channel.app.net/stream/user` and can be accessed via WebSocket or standard HTTP: + +* `wss://stream-channel.app.net/stream/user` +* `https://stream-channel.app.net/stream/user` + +If authentication fails or hits a rate limit, your client will be disconnected immediately with the appropriate HTTP error code. + +The client can optionally supply an `connection_id` in the query string. The user stream endpoint will return the negotiated `connection_id` in HTTP headers (https) or initial message (websocket). This MAY be the same `connection_id` requested, if client was able to resume streaming on a previous endpoint. If it does NOT match, client should assume that subscriptions must be recreated, and should make efforts to backfill via the JSON API. + +Other clients consuming the same `connection_id` will be disconnected. We will make a best-effort attempt to allow for replay of events upon reconnection; this behavior is designed to be available for approximately 600 seconds between connections. + +### Client subscribes to updates + +Based on the previous client state (if available), the client makes a number of backfill requests via the JSON API, as it would if streaming was unavailable. If a subscription is desired, the `connection_id` parameter can be supplied with each request. Creation of subscriptions is idempotent, but subscriptions are only created if: + +1. `count` is zero or positive (defaults to 20), and +2. one of the following is true: + * the `since_id` parameter was specified, the `before_id` parameter was not specified, and the `more` value in the returned `meta` object is `false`, or + * no pagination parameters were specified, or + * no pagination is supported on that endpoint (currently all available endpoints are paginated) + +The presence of the `subscription_id` value in the returned `meta` object indicates a subscription has been created or updated. + +Requests for subscriptions can also contain a `subscription_id`, which is e.g., a UUID or short mnemonic string chosen by the client designed to uniquely identify that subscription. Client-supplied `subscription_id`s are considered opaque to App.net. This will be returned in the `meta` object of each returned message, as well as the HTTP response when a subscription is created, to help with message ordering. If a `subscription_id` is not supplied, one will be generated. The (`connection_id`, `subscription_id`) tuple must be globally unique, but `subscription_id`s can be reused between user streams. Each stream can have at most 50 subscriptions. A stream could be subscribed to the same API endpoint with multiple subscription_ids. Make sure you save the returned `subscription_id` so your streaming consumer knows which API call streaming messages belong to. + +Clients may begin receiving events on the stream **before** the JSON API call returns, so it is recommended that stream consumers pre-allocate subscription IDs and queue any events received until after the final subscription call returns. Subscription requests with an existing `subscription_id` will overwrite any previous subscription on that endpoint. + +### Client consumes stream events + +Each stream message is a JSON blob that matches the [response format](/docs/basics/responses/#response-envelope) returned by the JSON API. If you are consuming a User Stream with WebSockets, each frame will be a separate JSON blob. If you are using the HTTP interface, the response will be encoded with ```Transfer-Encoding: chunked``` and each stream message is separated by ```\r\n```. + +Once the JSON is parsed, each message will include the `subscription_ids` which is a list of all subscriptions this message matches. If the original endpoint supported pagination, updated pagination keys `max_id`, `min_id` and `more` will be included. `more` will always be false in the case of streaming events. Events may contain multiple data objects. The `subscription_ids` should be used by your stream consumer to decide how to process the streaming event. + +Ordering is not guaranteed for events delivered on streams, but we aim to have the ordering be reasonably correct. Depending on your application, you may wish to reorder items for display. + +## Available Endpoints + +* /stream/0/users/me/following +* /stream/0/users/me/followers +* /stream/0/users/me/posts +* /stream/0/users/me/mentions +* /stream/0/posts/stream +* /stream/0/posts/stream/unified +* /stream/0/channels (includes new messages for channels you're subscribed to) +* /stream/0/channels/:channel_id/subscribers +* /stream/0/channels/:channel_id/messages +* /stream/0/users/me/files + +## Limits + +* Each User Stream expires approximately 5 minutes after the connection is closed +* Each user token can create at most 5 User Streams +* Each User Stream can have at most 50 subscriptions. The same endpoint can be subscribed to multiple times. + +## Subscription options + +The App.net API accepts many query string parameters (`include_deleted`, `include_html`, etc) to customize and filter the data returned. These query string parameters are also respected by the User Streaming API with an important caveat. "Display options" are a connection-wide property and must be specified when a User Stream is created. "Filter options" are provided per subscription. + +For example, if I never want to receive the `html` attribute over my user stream, when I connect I can specify that: + + curl -i -H 'Authorization: BEARER ...' "https://stream-channel.app.net/stream/user?include_html=0" + +But if I want to only receive File notifications for complete files, when I subscribe to my Files, I can specify that option: + + curl -H 'Authorization: BEARER ...' "https://alpha-api.app.net/stream/0/users/me/files?connection_id=...&include_incomplete=0" + +The display options that may be specified when a User Stream is created are: + +* include_annotations +* include_message_annotations +* include_channel_annotations +* include_user_annotations +* include_post_annotations +* include_file_annotations +* include_starred_by +* include_reposters +* include_marker +* include_recent_message +* include_html + +The filter options that may be specified when creating a subscription are: + +* include_incomplete +* include_private +* file_types +* channel_types +* include_read +* include_muted +* include_deleted +* include_machine +* include_directed_posts + +## Deleted Objects + +In general, the User Streams API tries to mimc the format and conventions of the rest of the App.net API. For deleted objects (posts, unfollows, files, etc), this isn't always possible. Deleted objects will always have `meta.is_deleted == true` and `meta.deleted_id` set to the identifier of the object that was removed. If possible, App.net will return a complete `data` object but that is not always possible. + +~~~js +{ + "meta": { + "is_deleted": true, + "deleted_id": "1212", + "subscription_ids": ["bf42ca05-e67e-4e26-8bd0-8b042dd5b04c"], + "connection_id": "Ne1Rpr4DgmilaYUCe51aoRQpCDei14Aw" + } +} +~~~ + +## Examples + +1. Create a User Stream: + + curl -i -H 'Authorization: BEARER ...' "https://stream-channel.app.net/stream/user" + + Connection-Id: sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf + +1. In a second terminal, add a subscription: + + curl -H 'Authorization: BEARER ...' "https://alpha-api.app.net/stream/0/posts/stream/unified?connection_id=sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf" + + Will return: + + { + "meta": { + "code": 200, + "subscription_ids": ["d3b72b23-f8d7-4108-a4f1-3aaa25328286"], + "marker": { + "id": "5668480", + "last_read_id": "5668480", + "name": "unified", + "percentage": 0, + "updated_at": "2013-05-14T20:18:16Z", + "version": "eMKC1BskFw8hL5q7FfTItiqgr4s" + }, + "max_id": "5675954", + "min_id": "5675037", + "more": true + }, + "data": [ + ... posts ... + ] + } + +1. When you receive a message, it will look like: + + { + "meta": { + "subscription_ids": ["d3b72b23-f8d7-4108-a4f1-3aaa25328286"], + "min_id": "5675993", + "max_id": "5675993", + "connection_id": "Ne1Rpr4DgmilaYUCe51aoRQpCDei14Aw", + "more": false + }, + "data": [ + ... posts ... + ] + } + +<%= render 'partials/endpoints-tab', :for => "user-stream" %> diff --git a/content/docs/resources/user-stream/lifecycle.md b/content/docs/resources/user-stream/lifecycle.md new file mode 100644 index 0000000..d746ad7 --- /dev/null +++ b/content/docs/resources/user-stream/lifecycle.md @@ -0,0 +1,44 @@ +--- +title: "User Stream Lifecycle" +--- + +# User Stream Lifecycle + +* TOC +{:toc} + +## Delete a User Stream + +Delete a [User Stream](/docs/resources/user-stream/). The User Stream must belong to the current token. It disconnects any sockets with this User Stream open and returns an HTTP 204 No Content on success. + +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* + +<%= endpoint "DELETE", "users/me/streams/[connection_id]", "User" %> + +<%= url_params [ + ["connection_id", "The connection id of the User Stream to delete."] +]%> + +#### Example + +> DELETE https://alpha-api.app.net/stream/0/streams/sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf +> +> 204 No Content + +## Delete a User Stream subscription + +Delete a subscription of a [User Stream](/docs/resources/user-stream/). The User Stream must belong to the current token. It returns an HTTP 204 No Content on success. + +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* + +<%= endpoint "DELETE", "users/me/streams/[connection_id]/[subscription_id]", "User" %> + +<%= url_params [ + ["connection_id", "The connection id of the User Stream the subscription belongs to."], + ["subscription_id", "The subscription id of the subscription to cancel"] +]%> +#### Example + +> DELETE https://alpha-api.app.net/stream/0/streams/sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf/bf42ca05-e67e-4e26-8bd0-8b042dd5b04c +> +> 204 No Content diff --git a/layouts/default.html b/layouts/default.html index 6e026f9..a454ba0 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -113,6 +113,10 @@ +
  • User Stream
    • +
  • Filter
    • Lifecycle
      • diff --git a/layouts/partials/endpoints/stream.md b/layouts/partials/endpoints/app-stream.md similarity index 100% rename from layouts/partials/endpoints/stream.md rename to layouts/partials/endpoints/app-stream.md diff --git a/layouts/partials/endpoints/user-stream.md b/layouts/partials/endpoints/user-stream.md new file mode 100644 index 0000000..5685c87 --- /dev/null +++ b/layouts/partials/endpoints/user-stream.md @@ -0,0 +1,24 @@ +
    Fieldobject
    - +
    @@ -176,7 +176,7 @@ Access control lists (ACLs) specify who can read and who can write +
    Field Type
    diff --git a/layouts/partials/endpoints/channel.md b/layouts/partials/endpoints/channel.md index 2234d92..e55924a 100644 --- a/layouts/partials/endpoints/channel.md +++ b/layouts/partials/endpoints/channel.md @@ -1,4 +1,4 @@ -
    Method
    +
    diff --git a/layouts/partials/endpoints/explore-stream.md b/layouts/partials/endpoints/explore-stream.md index 9400eeb..d9bbe88 100644 --- a/layouts/partials/endpoints/explore-stream.md +++ b/layouts/partials/endpoints/explore-stream.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/file.md b/layouts/partials/endpoints/file.md index e8ab9b6..1b86c3b 100644 --- a/layouts/partials/endpoints/file.md +++ b/layouts/partials/endpoints/file.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/interaction.md b/layouts/partials/endpoints/interaction.md index 973ed71..817cb8e 100644 --- a/layouts/partials/endpoints/interaction.md +++ b/layouts/partials/endpoints/interaction.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/message.md b/layouts/partials/endpoints/message.md index d65a4f9..44f0fc9 100644 --- a/layouts/partials/endpoints/message.md +++ b/layouts/partials/endpoints/message.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/place.md b/layouts/partials/endpoints/place.md index 1cc5457..5e0959a 100644 --- a/layouts/partials/endpoints/place.md +++ b/layouts/partials/endpoints/place.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/post.md b/layouts/partials/endpoints/post.md index 5a498f1..3480a41 100644 --- a/layouts/partials/endpoints/post.md +++ b/layouts/partials/endpoints/post.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/stream-marker.md b/layouts/partials/endpoints/stream-marker.md index cf682ed..dde71fb 100644 --- a/layouts/partials/endpoints/stream-marker.md +++ b/layouts/partials/endpoints/stream-marker.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/stream.md b/layouts/partials/endpoints/stream.md index 6a4250a..7672e1b 100644 --- a/layouts/partials/endpoints/stream.md +++ b/layouts/partials/endpoints/stream.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/text-processor.md b/layouts/partials/endpoints/text-processor.md index 9d3358b..328688d 100644 --- a/layouts/partials/endpoints/text-processor.md +++ b/layouts/partials/endpoints/text-processor.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/token.md b/layouts/partials/endpoints/token.md index 7197735..9bd9173 100644 --- a/layouts/partials/endpoints/token.md +++ b/layouts/partials/endpoints/token.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/endpoints/user.md b/layouts/partials/endpoints/user.md index 4fd7c0b..80dc5af 100644 --- a/layouts/partials/endpoints/user.md +++ b/layouts/partials/endpoints/user.md @@ -1,4 +1,4 @@ -
    Description
    +
    diff --git a/layouts/partials/parameters.md b/layouts/partials/parameters.md index a25a9e9..7dcd653 100644 --- a/layouts/partials/parameters.md +++ b/layouts/partials/parameters.md @@ -1,6 +1,6 @@ #### <%= header %> -
    Description
    +
    diff --git a/static/css/style.css b/static/css/style.css index dcc36a6..d9b905d 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -1,7 +1,7 @@ /* we're currently modifying bootstrap.css to apply 'table' and 'table-striped' styles to all tables */ .content { - padding-bottom: 100px; + padding-bottom: 100px; } .label-GET { @@ -20,6 +20,43 @@ background-color: #b94a48; } +.alert, pre { + -webkit-border-radius: 0px; + -moz-border-radius: 0px; + border-radius: 0px; + border: 0; +} + +.alert-success { + background-color: #f8fcf6; +} + +.alert-error { + background-color: #faecec; +} + +.alert-info { + background-color: #eaf8ff; +} + +body { + font-family: "Helvetica Neue",Helvetica,Arial,sans-serif; + font-size: 14px; + line-height: 18px; +} + +body h2 { + font-size: 20px; + line-height: 20px; + margin-bottom: 12px; +} + +body h2, body h3, body h4, body h5 { + margin-top: 2em; + margin-bottom: .5em; +} + + ul.nav-list ul.nav-list ul.nav-list li a { padding-left: 50px; } From a412d4466856b0a5b76a70aac22370b011f40f24 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 11 Apr 2013 09:38:18 -0700 Subject: [PATCH 037/231] Let you have a local_config.yml --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index da9665c..a822ded 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ Gemfile.lock bin vendor .bundle +local_config.yml From 00c75d0936db37ae07f1a4f1db1108da709ff2a1 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 11 Apr 2013 10:27:33 -0700 Subject: [PATCH 038/231] New styles --- static/css/style.css | 54 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 51 insertions(+), 3 deletions(-) diff --git a/static/css/style.css b/static/css/style.css index d9b905d..d6e2646 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -20,6 +20,36 @@ background-color: #b94a48; } +.label-GET, .label-POST, .label-PUT, .label-DELETE { + color: #fff; + padding: 1px 2px; +} + +body a { + color: #0088cc; + text-decoration: none; +} + +body a:hover { + color: #005580; + text-decoration: underline; +} + +body a:visited { + color: #0088cc; + text-decoration: none; +} + +code { + font-size: 12px; + white-space: nowrap; + /* color: #4a484c; */ +} + +pre { + background-color: #ececec; +} + .alert, pre { -webkit-border-radius: 0px; -moz-border-radius: 0px; @@ -29,14 +59,17 @@ .alert-success { background-color: #f8fcf6; + color: #468847; } .alert-error { background-color: #faecec; + color: #b94a48; } .alert-info { background-color: #eaf8ff; + color: #3a87ad; } body { @@ -45,13 +78,28 @@ body { line-height: 18px; } +body h1, body h2, body h3 { + line-height: 40px; +} + +body h1 { + font-size: 38.5px;; +} + body h2 { - font-size: 20px; - line-height: 20px; - margin-bottom: 12px; + font-size: 31.5px; +} + +body h3 { + font-size: 24.5px; +} + +body h4 { + font-size: 17.5px; } body h2, body h3, body h4, body h5 { + color: #4a484c; margin-top: 2em; margin-bottom: .5em; } From 4ccb1e3eb4b51d20da52b28395130466cf8fdf76 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 11 Apr 2013 12:33:51 -0700 Subject: [PATCH 039/231] Add social button section, isn't linked too yet --- config.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/config.yaml b/config.yaml index 26b52fd..2596636 100644 --- a/config.yaml +++ b/config.yaml @@ -86,4 +86,4 @@ watcher: notify_on_compilation_failure: true local_hostname: "localhost" -lanai_hostname: "sandbox.app.net" +lanai_hostname: "account.sandbox.app.net" From 0140a9540b97ca549a05b05e7e913039515b9170 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 11 Apr 2013 12:33:51 -0700 Subject: [PATCH 040/231] Add social button section, isn't linked too yet --- config.yaml | 2 +- content/docs/other/social-buttons.md | 70 ++++++++++++++++++++++++++++ 2 files changed, 71 insertions(+), 1 deletion(-) create mode 100644 content/docs/other/social-buttons.md diff --git a/config.yaml b/config.yaml index 26b52fd..2596636 100644 --- a/config.yaml +++ b/config.yaml @@ -86,4 +86,4 @@ watcher: notify_on_compilation_failure: true local_hostname: "localhost" -lanai_hostname: "sandbox.app.net" +lanai_hostname: "account.sandbox.app.net" diff --git a/content/docs/other/social-buttons.md b/content/docs/other/social-buttons.md new file mode 100644 index 0000000..4ebb5dd --- /dev/null +++ b/content/docs/other/social-buttons.md @@ -0,0 +1,70 @@ +--- +title: "Social Buttons" +--- + +# Social Buttons + +* TOC +{:toc} + +Social buttons are meant to be an easy way to include a [web intent](/docs/other/web-intents/) on any web page. + +## The Share on App.net Button + +The share buttons hooks up to our [Post Intent](/docs/other/web-intents/#the-post-intent). It's an easy way for publishers to pre-compose a message for user. The user will still have an option to edit any pre-composed message. + +### Including the button on your site. + +There are two parts to including this on button your site. The first part is a small bit of CSS that can be included in any pre-exsisting styles you have, or it ca be including inline with the button. Here is a template you can use to build a share on App.net button. + +You will need to replace {{ URL Encoded Message }} with a pre-composed URL Encoded Message of your choosing. + +#### The CSS Portion + +~~~css +a.adn-button { + background-color: #C75244; + color: #FFFFFF; + text-decoration: none; + display: inline-block; + font-size: 22px; + line-height: 22px; + padding: 10px 20px; +} +a.adn-button:visited { + color: #FFFFFF; +} + +a.adn-button:hover { + background-color: #CA5D4E; +} +~~~ + +#### The HTML Portion + +~~~html +Share on App.net +~~~ + +### An Example + +Here is an example of a button that fills in a message like "Check out the App.net docs http://developers.app.net" + + +Share on App.net \ No newline at end of file From bb3f33d84b4718b3d51f230b77561ea8a82fe6d6 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 11 Apr 2013 14:03:11 -0700 Subject: [PATCH 041/231] Rounded corners to the button --- content/docs/other/social-buttons.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/content/docs/other/social-buttons.md b/content/docs/other/social-buttons.md index 4ebb5dd..9be2a4a 100644 --- a/content/docs/other/social-buttons.md +++ b/content/docs/other/social-buttons.md @@ -30,6 +30,9 @@ a.adn-button { font-size: 22px; line-height: 22px; padding: 10px 20px; + border-radius: 22px; + -webkit-border-radius: 22px; + -moz-border-radius: 22px; } a.adn-button:visited { color: #FFFFFF; @@ -59,12 +62,16 @@ Here is an example of a button that fills in a message like "Check out the App.n font-size: 22px; line-height: 22px; padding: 10px 20px; + border-radius: 22px; + -webkit-border-radius: 22px; + -moz-border-radius: 22px; } a.adn-button:visited { color: #FFFFFF; } a.adn-button:hover { background-color: #CA5D4E; + text-decoration: none; } Share on App.net \ No newline at end of file From b3e05fb7c5d57e4a299400ec8c447b15d97af105 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Fri, 12 Apr 2013 11:30:07 -0700 Subject: [PATCH 042/231] Adding the follow intent to the docs --- content/docs/other/social-buttons.md | 6 +++++- content/docs/other/web-intents.md | 16 +++++++++++++--- static/css/style.css | 4 ++++ 3 files changed, 22 insertions(+), 4 deletions(-) diff --git a/content/docs/other/social-buttons.md b/content/docs/other/social-buttons.md index 9be2a4a..6240d9d 100644 --- a/content/docs/other/social-buttons.md +++ b/content/docs/other/social-buttons.md @@ -74,4 +74,8 @@ Here is an example of a button that fills in a message like "Check out the App.n text-decoration: none; } -Share on App.net \ No newline at end of file +Share on App.net + +## The Follow Me on App.net Button + +the follow button hooks up with our Follow Intent () \ No newline at end of file diff --git a/content/docs/other/web-intents.md b/content/docs/other/web-intents.md index da29ca5..b0bb807 100644 --- a/content/docs/other/web-intents.md +++ b/content/docs/other/web-intents.md @@ -11,18 +11,28 @@ Web intents are an easy way to integrate with App.net; you don't even need to us ## The Post Intent -Currently, the only supported intent is the Post Intent. It allows you to create a link that will present the user with a post creation box and any pre-filled text that you may have supplied. +The post intent allows you to create a link that will present the user with a post creation box and any pre-filled text that you may have supplied. -The base URL for this intent is ```https://alpha.app.net/intent/post```. +The base URL for this intent is ```https://alpha.app.net/intent/post/```. You may optionally prepopulate the post creation box by supplying a ```text``` query parameter to the URL. -For example, this URL ```https://alpha.app.net/intent/post?text=@voidfiles+save+some+coffee+for+me``` will create a post that reads: +For example, this URL ```https://alpha.app.net/intent/post/?text=@voidfiles+save+some+coffee+for+me``` will create a post that reads: @voidfiles save some coffee for me At this point the end user will be able to edit and then submit the post. +## The Follow Intent + +The follow intent is an easy way to link to a page on App.net that will present the user with an opportunity to follow a selected user. + +The base URL for this intent is ```https://alpha.app.net/intent/follow/```. + +You must include a user that is the intended target of the follow action. To do this include a ```user_id``` query parameter in the URL. The ```user_id``` can be a username prepended by a @, like @adn, or it can be the numeric user_id, like 136. + +For example, this URL ```https://alpha.app.net/intent/follow/?user_id=136``` will show page where the user can choose to follow the user @adn: + ## Javascript & Intents While you don't need to write any Javascript to use intents, it does make for a nicer experience. If you want to, you can use Javascript to open the intents dialog in a popup window. diff --git a/static/css/style.css b/static/css/style.css index d6e2646..972094b 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -50,6 +50,10 @@ pre { background-color: #ececec; } +pre code { + white-space: pre-wrap; +} + .alert, pre { -webkit-border-radius: 0px; -moz-border-radius: 0px; From d36fbc1a3b6b5db81a1c5c066e18c8a4437d602a Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Fri, 12 Apr 2013 16:02:37 -0700 Subject: [PATCH 043/231] Add follow social button, and moved to pygments.rb from coderay --- Rules | 3 +- content/docs/other/social-buttons.md | 88 +++++++++++++--------------- layouts/partials/buttons/button.css | 16 +++++ static/css/style.css | 74 +++++++++++++++++++++-- 4 files changed, 129 insertions(+), 52 deletions(-) create mode 100644 layouts/partials/buttons/button.css diff --git a/Rules b/Rules index f7dca76..d2c40bc 100644 --- a/Rules +++ b/Rules @@ -21,7 +21,8 @@ compile '*' do # don’t filter binary items else filter :erb - filter :kramdown, :toc_levels => [2], :coderay_line_numbers => nil + filter :kramdown, :toc_levels => [2], :enable_coderay => false + filter :colorize_syntax, :default_colorizer => :pygmentsrb, :linenos => 'inline' layout 'default' end end diff --git a/content/docs/other/social-buttons.md b/content/docs/other/social-buttons.md index 6240d9d..f8da33f 100644 --- a/content/docs/other/social-buttons.md +++ b/content/docs/other/social-buttons.md @@ -13,69 +13,65 @@ Social buttons are meant to be an easy way to include a [web intent](/docs/other The share buttons hooks up to our [Post Intent](/docs/other/web-intents/#the-post-intent). It's an easy way for publishers to pre-compose a message for user. The user will still have an option to edit any pre-composed message. -### Including the button on your site. +## The Follow Me on App.net Button -There are two parts to including this on button your site. The first part is a small bit of CSS that can be included in any pre-exsisting styles you have, or it ca be including inline with the button. Here is a template you can use to build a share on App.net button. +the follow button hooks up with our [Follow Intent](/docs/other/web-intents/#the-follow-intent). It's an easy way to link to a page on app.net where a user can then follow you. -You will need to replace {{ URL Encoded Message }} with a pre-composed URL Encoded Message of your choosing. + +### Including a button on your site. + +There are two parts to including this on button your site. The first part is a small bit of CSS that can be included in any pre-exsisting styles you have, or it ca be including inline with the button. Here is a template you can use to build a share on App.net button. #### The CSS Portion ~~~css -a.adn-button { - background-color: #C75244; - color: #FFFFFF; - text-decoration: none; - display: inline-block; - font-size: 22px; - line-height: 22px; - padding: 10px 20px; - border-radius: 22px; - -webkit-border-radius: 22px; - -moz-border-radius: 22px; -} -a.adn-button:visited { - color: #FFFFFF; -} - -a.adn-button:hover { - background-color: #CA5D4E; -} +<%= render 'partials/buttons/button' %> ~~~ #### The HTML Portion + +##### Share on App.net Button + +You will need to replace ```{{ URL Encoded Message }}``` with a pre-composed URL Encoded Message of your choosing. + ~~~html -Share on App.net +Share on App.net ~~~ -### An Example +##### Follow Me on App.net Button + +You will need to replace ```{{ USER_ID }}``` with either a number user id like, 136, or a username prepended with an @ like, @adn. -Here is an example of a button that fills in a message like "Check out the App.net docs http://developers.app.net" +~~~html +Follow Me on App.net +~~~ + +### Examples + +#### Post Button Example +Here is an example of a post button that fills in a message like "Check out the App.net docs http://developers.app.net" + Share on App.net -## The Follow Me on App.net Button -the follow button hooks up with our Follow Intent () \ No newline at end of file +~~~html +Share on App.net +~~~ + +#### Follow Button Example + +Here is an example of a follow button that asks the user to follow the @adn account. + + +Follow Me on App.net + + +~~~html +Follow Me on App.net +~~~ + diff --git a/layouts/partials/buttons/button.css b/layouts/partials/buttons/button.css new file mode 100644 index 0000000..61f6d73 --- /dev/null +++ b/layouts/partials/buttons/button.css @@ -0,0 +1,16 @@ +a.adn-button, a.adn-button:visited, a.adn-button:hover { + background-color: #C75244; + color: #FFFFFF; + text-decoration: none; + display: inline-block; + font-size: 18px; + line-height: 18px; + padding: 10px 20px; + border-radius: 18px; + -webkit-border-radius: 18px; + -moz-border-radius: 18px; +} + +a.adn-button:hover { + background-color: #CA5D4E; +} \ No newline at end of file diff --git a/static/css/style.css b/static/css/style.css index 972094b..5a65dcf 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -50,10 +50,6 @@ pre { background-color: #ececec; } -pre code { - white-space: pre-wrap; -} - .alert, pre { -webkit-border-radius: 0px; -moz-border-radius: 0px; @@ -159,4 +155,72 @@ html.breakpoint-phone .container { html.breakpoint-tablet .nav-list { margin-right: 0; width: auto; -} \ No newline at end of file +} +pre code { + white-space: pre-wrap; +} +pre code, pre {background-color:#073642;color:#93a1a1} +pre code .c{color:#586e75 !important;font-style:italic !important} +pre code .cm{color:#586e75 !important;font-style:italic !important} +pre code .cp{color:#586e75 !important;font-style:italic !important} +pre code .c1{color:#586e75 !important;font-style:italic !important} +pre code .cs{color:#586e75 !important;font-weight:bold !important;font-style:italic !important} +pre code .err{color:#dc322f !important;background:none !important} +pre code .k{color:#cb4b16 !important} +pre code .o{color:#93a1a1 !important;font-weight:bold !important} +pre code .p{color:#93a1a1 !important} +pre code .ow{color:#2aa198 !important;font-weight:bold !important} +pre code .gd{color:#93a1a1 !important;background-color:#372c34 !important;display:inline-block} +pre code .gd .x{color:#93a1a1 !important;background-color:#4d2d33 !important;display:inline-block} +pre code .ge{color:#93a1a1 !important;font-style:italic !important} +pre code .gr{color:#aa0000} +pre code .gh{color:#586e75 !important} +pre code .gi{color:#93a1a1 !important;background-color:#1a412b !important;display:inline-block} +pre code .gi .x{color:#93a1a1 !important;background-color:#355720 !important;display:inline-block} +pre code .go{color:#888888} +pre code .gp{color:#555555} +pre code .gs{color:#93a1a1 !important;font-weight:bold !important} +pre code .gu{color:#6c71c4 !important} +pre code .gt{color:#aa0000} +pre code .kc{color:#859900 !important;font-weight:bold !important} +pre code .kd{color:#268bd2 !important} +pre code .kp{color:#cb4b16 !important;font-weight:bold !important} +pre code .kr{color:#d33682 !important;font-weight:bold !important} +pre code .kt{color:#2aa198 !important} +pre code .n{color:#268bd2 !important} +pre code .na{color:#268bd2 !important} +pre code .nb{color:#859900 !important} +pre code .nc{color:#d33682 !important} +pre code .no{color:#b58900 !important} +pre code .ni{color:#800080} +pre code .nl{color:#859900 !important} +pre code .ne{color:#268bd2 !important;font-weight:bold !important} +pre code .nf{color:#268bd2 !important;font-weight:bold !important} +pre code .nn{color:#b58900 !important} +pre code .nt{color:#268bd2 !important;font-weight:bold !important} +pre code .nx{color:#b58900 !important} +pre code .bp{color:#999999} +pre code .vc{color:#008080} +pre code .vg{color:#268bd2 !important} +pre code .vi{color:#268bd2 !important} +pre code .nv{color:#268bd2 !important} +pre code .w{color:#bbbbbb} +pre code .mf{color:#2aa198 !important} +pre code .m{color:#2aa198 !important} +pre code .mh{color:#2aa198 !important} +pre code .mi{color:#2aa198 !important} +pre code .mo{color:#009999} +pre code .s{color:#2aa198 !important} +pre code .sb{color:#d14} +pre code .sc{color:#d14} +pre code .sd{color:#2aa198 !important} +pre code .s2{color:#2aa198 !important} +pre code .se{color:#dc322f !important} +pre code .sh{color:#d14} +pre code .si{color:#268bd2 !important} +pre code .sx{color:#d14} +pre code .sr{color:#2aa198 !important} +pre code .s1{color:#2aa198 !important} +pre code .ss{color:#990073} +pre code .il{color:#009999} +pre code div .gd,.highlight div .gd .x,.highlight div .gi,.highlight div .gi .x{display:inline-block;width:100%} From 0aa349db7a830359d57057532ec8c747e7b881a4 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Mon, 15 Apr 2013 14:18:34 -0700 Subject: [PATCH 044/231] Intent & Social doc updates --- content/docs/other/social-buttons.md | 65 +++++++++++++--------------- content/docs/other/web-intents.md | 10 +++-- 2 files changed, 37 insertions(+), 38 deletions(-) diff --git a/content/docs/other/social-buttons.md b/content/docs/other/social-buttons.md index f8da33f..ee76ce2 100644 --- a/content/docs/other/social-buttons.md +++ b/content/docs/other/social-buttons.md @@ -6,32 +6,15 @@ title: "Social Buttons" * TOC {:toc} +Use social buttons to let visitors to your website [share content](#share-on-appnet-button) and [follow you](#follow-me-on-appnet-button) on App.net. -Social buttons are meant to be an easy way to include a [web intent](/docs/other/web-intents/) on any web page. +Social buttons are meant to be an easy way to include a [social interaction](/docs/other/web-intents/) on any web page. -## The Share on App.net Button +## Share on App.net Button -The share buttons hooks up to our [Post Intent](/docs/other/web-intents/#the-post-intent). It's an easy way for publishers to pre-compose a message for user. The user will still have an option to edit any pre-composed message. +The share on App.net button is an easy way to let visitors to your website share content directly to App.net. -## The Follow Me on App.net Button - -the follow button hooks up with our [Follow Intent](/docs/other/web-intents/#the-follow-intent). It's an easy way to link to a page on app.net where a user can then follow you. - - -### Including a button on your site. - -There are two parts to including this on button your site. The first part is a small bit of CSS that can be included in any pre-exsisting styles you have, or it ca be including inline with the button. Here is a template you can use to build a share on App.net button. - -#### The CSS Portion - -~~~css -<%= render 'partials/buttons/button' %> -~~~ - -#### The HTML Portion - - -##### Share on App.net Button +#### HTML You will need to replace ```{{ URL Encoded Message }}``` with a pre-composed URL Encoded Message of your choosing. @@ -39,18 +22,15 @@ You will need to replace ```{{ URL Encoded Message }}``` with a pre-composed URL Share on App.net ~~~ -##### Follow Me on App.net Button +#### Example -You will need to replace ```{{ USER_ID }}``` with either a number user id like, 136, or a username prepended with an @ like, @adn. +Here is an example of a post button that fills in a message like "Check out the App.net Developer docs http://developers.app.net" ~~~html -Follow Me on App.net +Share on App.net ~~~ -### Examples - -#### Post Button Example -Here is an example of a post button that fills in a message like "Check out the App.net docs http://developers.app.net" +this is what that would look like: - -Share on App.net - - -### Follow Me on App.net Button - -The follow me on App.net button let's visitors to your website easily follow you on App.net. - -#### HTML - -You will need to replace ```{{ USER_ID }}``` with either a number user id like, 136, or a username prepended with an @ like, @adn. - -~~~html -Follow Me on App.net -~~~ - -#### Example - -Here is an example of a follow button that asks the user to follow the @adn account. - -~~~html -Follow Me on App.net -~~~ - -this is what that would look like: - -Follow Me on App.net - - -## Common CSS - -In order to integrate an App.net social button into your website, you'll have to complete two steps. Step one, for all buttons, is to add a little bit of CSS into any pre-existing style sheets you have You also have the option of including the CSS inline with the button. - -~~~css -<%= render 'partials/buttons/button' %> -~~~ - diff --git a/content/docs/other/web-intents.md b/content/docs/other/web-intents.md index 3ef5944..00ccf3c 100644 --- a/content/docs/other/web-intents.md +++ b/content/docs/other/web-intents.md @@ -9,6 +9,11 @@ title: "Web Intents" Web intents are an easy way to integrate with App.net; you don't even need to use Javascript. Intents in their most basic form are just carefully constructed URLs. By clicking on an intent link, a user will be taken to a page on App.net with a prompt to carry out an action, such as creating a post. If the user is not logged in to App.net, she/he will first authenticate before being presented with the action dialog. + +
    +

    Note: If you just want a simple follow or share button you can use button builder instead. We've also open sourced the buttons so that you could host them your self. Checkout the github repo for more information on how to do that.

    +
    + ## The Post Intent The post intent allows you to create a link that will present the user with a post creation box and any pre-filled text that you may have supplied. @@ -31,18 +36,8 @@ The base URL for this intent is ```https://alpha.app.net/intent/follow/```. You must include a user that is the intended target of the follow action. To do this include a ```user_id``` query parameter in the URL. The ```user_id``` can be a username prepended by a @, like @adn, or it can be the numeric user_id, like 136. -For example, this URL ```https://alpha.app.net/intent/follow/?user_id=136``` will show page where the user can choose to follow the user @adn: - -## Javascript & Intents - -While you don't need to write any Javascript to use intents, it does make for a nicer experience. If you want to, you can use Javascript to open the intents dialog in a popup window. +For example, this URL ```https://alpha.app.net/intent/follow/?user_id=136``` will show page where the user can choose to follow the user @adn. -For example, the following Javascript will open a Post Intent in a popup. The popup should be at least 700 x 350 pixels. +## Using intents with buttons -~~~ -window.open( - 'https://alpha.app.net/intent/post?text=%40adn%20When%20is%20the%20next%20meetup%3F', - 'adn_post', - 'width=750,height=350,left=100,top=100' -); -~~~ \ No newline at end of file +You can \ No newline at end of file diff --git a/lib/helpers.rb b/lib/helpers.rb index 9147d81..cbc6c05 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -48,4 +48,8 @@ def pagination_note() def general_params_note_for(type) 'This endpoint responds to general '+type.capitalize+' parameters.' +end + +def env_var(name) + ENV[name] end \ No newline at end of file From d2638133c97caf2ed0ed65060ed42dcea7eaa95a Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 30 May 2013 11:38:11 -0700 Subject: [PATCH 073/231] New button docs and new env conf --- config.yaml | 3 -- config/production.yaml | 89 ------------------------------- config/staging.yaml | 89 ------------------------------- content/docs/other/web-intents.md | 17 ++++-- layouts/default.html | 2 +- static/css/style.css | 6 +++ 6 files changed, 20 insertions(+), 186 deletions(-) delete mode 100644 config/production.yaml delete mode 100644 config/staging.yaml diff --git a/config.yaml b/config.yaml index cd19d00..520fae9 100644 --- a/config.yaml +++ b/config.yaml @@ -84,6 +84,3 @@ watcher: # When to send notifications (using Growl or notify-send). notify_on_compilation_success: true notify_on_compilation_failure: true - -local_hostname: "mthurman-vm.dev.mxmlabs.com" -lanai_hostname: "account.mthurman-vm.dev.mxmlabs.com" diff --git a/config/production.yaml b/config/production.yaml deleted file mode 100644 index 7adc800..0000000 --- a/config/production.yaml +++ /dev/null @@ -1,89 +0,0 @@ -# Nanoc really doesn't have any sense of an environment -# Instead we have a different config file for each enviroment -# If you make a change to one config file, you need to make a change to all of them - - -# A list of file extensions that nanoc will consider to be textual rather than -# binary. If an item with an extension not in this list is found, the file -# will be considered as binary. -text_extensions: [ 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'ms', 'mustache', 'php', 'rb', 'sass', 'scss', 'txt', 'xhtml', 'xml' ] - -# The path to the directory where all generated files will be written to. This -# can be an absolute path starting with a slash, but it can also be path -# relative to the site directory. -output_dir: output_production - -# A list of index filenames, i.e. names of files that will be served by a web -# server when a directory is requested. Usually, index files are named -# “index.html”, but depending on the web server, this may be something else, -# such as “default.htm”. This list is used by nanoc to generate pretty URLs. -index_filenames: [ 'index.html' ] - -# Whether or not to generate a diff of the compiled content when compiling a -# site. The diff will contain the differences between the compiled content -# before and after the last site compilation. -enable_output_diff: false - -prune: - # Whether to automatically remove files not managed by nanoc from the output - # directory. For safety reasons, this is turned off by default. - auto_prune: false - - # Which files and directories you want to exclude from pruning. If you version - # your output directory, you should probably exclude VCS directories such as - # .git, .svn etc. - exclude: [ '.git', '.hg', '.svn', 'CVS' ] - -# The data sources where nanoc loads its data from. This is an array of -# hashes; each array element represents a single data source. By default, -# there is only a single data source that reads data from the “content/” and -# “layout/” directories in the site directory. -data_sources: - - - # The type is the identifier of the data source. By default, this will be - # `filesystem_unified`. - type: filesystem_unified - - # The path where items should be mounted (comparable to mount points in - # Unix-like systems). This is “/” by default, meaning that items will have - # “/” prefixed to their identifiers. If the items root were “/en/” - # instead, an item at content/about.html would have an identifier of - # “/en/about/” instead of just “/about/”. - items_root: / - - # The path where layouts should be mounted. The layouts root behaves the - # same as the items root, but applies to layouts rather than items. - layouts_root: / - - # Whether to allow periods in identifiers. When turned off, everything - # past the first period is considered to be the extension, and when - # turned on, only the characters past the last period are considered to - # be the extension. For example, a file named “content/about.html.erb” - # will have the identifier “/about/” when turned off, but when turned on - # it will become “/about.html/” instead. - allow_periods_in_identifiers: false - - - - type: static - items_root: /static - -# Configuration for the “watch” command, which watches a site for changes and -# recompiles if necessary. -watcher: - # A list of directories to watch for changes. When editing this, make sure - # that the “output/” and “tmp/” directories are _not_ included in this list, - # because recompiling the site will cause these directories to change, which - # will cause the site to be recompiled, which will cause these directories - # to change, which will cause the site to be recompiled again, and so on. - dirs_to_watch: [ 'content', 'layouts', 'lib' ] - - # A list of single files to watch for changes. As mentioned above, don’t put - # any files from the “output/” or “tmp/” directories in here. - files_to_watch: [ 'config.yaml', 'Rules' ] - - # When to send notifications (using Growl or notify-send). - notify_on_compilation_success: true - notify_on_compilation_failure: true - -local_hostname: "developers.app.net" -lanai_hostname: "account.app.net" diff --git a/config/staging.yaml b/config/staging.yaml deleted file mode 100644 index 79fc075..0000000 --- a/config/staging.yaml +++ /dev/null @@ -1,89 +0,0 @@ -# Nanoc really doesn't have any sense of an environment -# Instead we have a different config file for each enviroment -# If you make a change to one config file, you need to make a change to all of them - - -# A list of file extensions that nanoc will consider to be textual rather than -# binary. If an item with an extension not in this list is found, the file -# will be considered as binary. -text_extensions: [ 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'ms', 'mustache', 'php', 'rb', 'sass', 'scss', 'txt', 'xhtml', 'xml' ] - -# The path to the directory where all generated files will be written to. This -# can be an absolute path starting with a slash, but it can also be path -# relative to the site directory. -output_dir: output_staging - -# A list of index filenames, i.e. names of files that will be served by a web -# server when a directory is requested. Usually, index files are named -# “index.html”, but depending on the web server, this may be something else, -# such as “default.htm”. This list is used by nanoc to generate pretty URLs. -index_filenames: [ 'index.html' ] - -# Whether or not to generate a diff of the compiled content when compiling a -# site. The diff will contain the differences between the compiled content -# before and after the last site compilation. -enable_output_diff: false - -prune: - # Whether to automatically remove files not managed by nanoc from the output - # directory. For safety reasons, this is turned off by default. - auto_prune: false - - # Which files and directories you want to exclude from pruning. If you version - # your output directory, you should probably exclude VCS directories such as - # .git, .svn etc. - exclude: [ '.git', '.hg', '.svn', 'CVS' ] - -# The data sources where nanoc loads its data from. This is an array of -# hashes; each array element represents a single data source. By default, -# there is only a single data source that reads data from the “content/” and -# “layout/” directories in the site directory. -data_sources: - - - # The type is the identifier of the data source. By default, this will be - # `filesystem_unified`. - type: filesystem_unified - - # The path where items should be mounted (comparable to mount points in - # Unix-like systems). This is “/” by default, meaning that items will have - # “/” prefixed to their identifiers. If the items root were “/en/” - # instead, an item at content/about.html would have an identifier of - # “/en/about/” instead of just “/about/”. - items_root: / - - # The path where layouts should be mounted. The layouts root behaves the - # same as the items root, but applies to layouts rather than items. - layouts_root: / - - # Whether to allow periods in identifiers. When turned off, everything - # past the first period is considered to be the extension, and when - # turned on, only the characters past the last period are considered to - # be the extension. For example, a file named “content/about.html.erb” - # will have the identifier “/about/” when turned off, but when turned on - # it will become “/about.html/” instead. - allow_periods_in_identifiers: false - - - - type: static - items_root: /static - -# Configuration for the “watch” command, which watches a site for changes and -# recompiles if necessary. -watcher: - # A list of directories to watch for changes. When editing this, make sure - # that the “output/” and “tmp/” directories are _not_ included in this list, - # because recompiling the site will cause these directories to change, which - # will cause the site to be recompiled, which will cause these directories - # to change, which will cause the site to be recompiled again, and so on. - dirs_to_watch: [ 'content', 'layouts', 'lib' ] - - # A list of single files to watch for changes. As mentioned above, don’t put - # any files from the “output/” or “tmp/” directories in here. - files_to_watch: [ 'config.yaml', 'Rules' ] - - # When to send notifications (using Growl or notify-send). - notify_on_compilation_success: true - notify_on_compilation_failure: true - -local_hostname: "developers.sandbox.app.net" -lanai_hostname: "account.sandbox.app.net" diff --git a/content/docs/other/web-intents.md b/content/docs/other/web-intents.md index 00ccf3c..3a54a07 100644 --- a/content/docs/other/web-intents.md +++ b/content/docs/other/web-intents.md @@ -18,16 +18,25 @@ Web intents are an easy way to integrate with App.net; you don't even need to us The post intent allows you to create a link that will present the user with a post creation box and any pre-filled text that you may have supplied. -The base URL for this intent is ```https://alpha.app.net/intent/post/```. +The base URL for this intent is `https://alpha.app.net/intent/post/`. -You may optionally prepopulate the post creation box by supplying a ```text``` query parameter to the URL. +You may optionally prepopulate the post creation box by supplying a `text` query parameter to the URL. -For example, this URL ```https://alpha.app.net/intent/post/?text=%40adn%20When%20is%20the%20next%20meetup%3F``` will create a post that reads: +For example, this URL `https://alpha.app.net/intent/post/?text=%40adn%20When%20is%20the%20next%20meetup%3F` will create a post that reads: - @adn When is the next meetup? +> @adn When is the next meetup? At this point the end user will be able to edit and then submit the post. +There is a second optional parameter: `url`. This allows you to automatically appended a URL to a post. + +For example, this URL: `https://alpha.app.net/intent/post/?text=%40adn%20Does%20this%20place%20work%3F&url=https%3A%2F%2Fmaps.google.com%2Fmaps%3Fq%3Dpublic%2Bhouse%2Bsf%26fb%3D1%26gl%3Dus%26hq%3Dpublic%2Bhouse%26hnear%3D0x80859a6d00690021%3A0x4a501367f076adff%2CSan%2BFrancisco%2C%2BCA%26cid%3D0%2C0%2C2651066427117992613%26t%3Dm%26z%3D16%26iwloc%3DA` will create a post that reads: + +> @adn Does this place work? https://maps.google.com/maps?q=public+… + +You'll notice that the displayed URL is automatically truncated to 40 chars. The full URL is included though. If your URL is less then 40 chars it will be included as is. + + ## The Follow Intent The follow intent is an easy way to link to a page on App.net that will present the user with an opportunity to follow a selected user. diff --git a/layouts/default.html b/layouts/default.html index e478819..beb566d 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -5,7 +5,7 @@ <%= @item[:title] %> - App.net API Documentation - + diff --git a/static/css/style.css b/static/css/style.css index 5a65dcf..5514ffc 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -156,6 +156,7 @@ html.breakpoint-tablet .nav-list { margin-right: 0; width: auto; } + pre code { white-space: pre-wrap; } @@ -224,3 +225,8 @@ pre code .s1{color:#2aa198 !important} pre code .ss{color:#990073} pre code .il{color:#009999} pre code div .gd,.highlight div .gd .x,.highlight div .gi,.highlight div .gi .x{display:inline-block;width:100%} + +p code { + word-break: break-all; + white-space: normal; +} \ No newline at end of file From 27a0adc2d60d34eab2a5ef9752bf89d5224ad37d Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 30 May 2013 11:52:34 -0700 Subject: [PATCH 074/231] Forgot to delete this section --- content/docs/other/web-intents.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/content/docs/other/web-intents.md b/content/docs/other/web-intents.md index 3a54a07..b323506 100644 --- a/content/docs/other/web-intents.md +++ b/content/docs/other/web-intents.md @@ -46,7 +46,3 @@ The base URL for this intent is ```https://alpha.app.net/intent/follow/```. You must include a user that is the intended target of the follow action. To do this include a ```user_id``` query parameter in the URL. The ```user_id``` can be a username prepended by a @, like @adn, or it can be the numeric user_id, like 136. For example, this URL ```https://alpha.app.net/intent/follow/?user_id=136``` will show page where the user can choose to follow the user @adn. - -## Using intents with buttons - -You can \ No newline at end of file From cfe093bcef197334297eabda0071eac194a6a029 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Mon, 3 Jun 2013 10:54:47 -0700 Subject: [PATCH 075/231] Add oEmbed to the docs --- content/docs/other/oembed.md | 37 ++++++++++++++++++++++++++++++++++++ layouts/default.html | 1 + lib/helpers.rb | 4 ++-- 3 files changed, 40 insertions(+), 2 deletions(-) create mode 100644 content/docs/other/oembed.md diff --git a/content/docs/other/oembed.md b/content/docs/other/oembed.md new file mode 100644 index 0000000..fd18c39 --- /dev/null +++ b/content/docs/other/oembed.md @@ -0,0 +1,37 @@ +--- +title: "oEmbed" +--- + +# oEmbed + +oEmbed is an open standard for turning a URL into an embeddable piece of content for your site. To find out more about oEmbed [read the spec](http://www.oembed.com/). The App.net oEmbed endpoint will return HTML snippets that you can include on your site. Right now it works for individual posts, and photos. + + +## oEmbed Endpoint + +Returns an oEmbed response for a given URL. + +<%= endpoint "GET", "oembed", "None", '', '' %> + +<%= url_params [ + ["url", "A URL for a post or photo on App.net."] +]%> + +#### Example + +> GET https://alpha-api.app.net/oembed?url=https%3A%2F%2Fposts.app.net%2F1 + +~~~ js +{ + "provider_url": "https://app.net/", + "version": "1.0", + "author_url": "https://alpha.app.net/mthurman", + "title": "join.app.net getting ready for the world w/ @dalton @berg @voidfiles @jhubball @aaronblyth @andrew @vinitlee @mark @mintz @barmstrong @laughingman @mikegreenspan @ben #joinus", + "url": "https://alpha.app.net/mthurman/post/1", + "provider_name": "App.net", + "type": "link", + "html": "...", + "author_name": "mthurman" +} +~~~ + diff --git a/layouts/default.html b/layouts/default.html index beb566d..b25edd0 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -135,6 +135,7 @@ diff --git a/lib/helpers.rb b/lib/helpers.rb index cbc6c05..73c7c0c 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -17,9 +17,9 @@ def migration_warning(migrations = []) end end -def endpoint(method, path, token, scope = "") +def endpoint(method, path, token, scope = "", base_path = 'stream/0/') path = path.gsub('[','{').gsub(']','}') - render '/partials/endpoint', :method => method, :path => 'https://alpha-api.app.net/stream/0/'+path, :token => token, :scope => scope + render '/partials/endpoint', :method => method, :path => 'https://alpha-api.app.net/' + base_path + path, :token => token, :scope => scope end def url_params(params = []) From 35c8e565775550b53c9c5f86782d73035e7fefea Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Mon, 3 Jun 2013 11:09:57 -0700 Subject: [PATCH 076/231] Fix case of oembed url --- layouts/default.html | 1 + 1 file changed, 1 insertion(+) diff --git a/layouts/default.html b/layouts/default.html index e478819..b8565a7 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -135,6 +135,7 @@ From e0a9c1f09ef1e9edb10a37baaacdcd8f970aa004 Mon Sep 17 00:00:00 2001 From: Brian Armstrong Date: Mon, 10 Jun 2013 17:13:21 -0700 Subject: [PATCH 077/231] invite_link now appears in user token --- content/docs/resources/token/index.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/content/docs/resources/token/index.md b/content/docs/resources/token/index.md index cd55d9a..0c4fd50 100644 --- a/content/docs/resources/token/index.md +++ b/content/docs/resources/token/index.md @@ -120,7 +120,8 @@ Requested with a user access token: "follows_you": false, "you_follow": true, "you_muted": false, - } + }, + "invite_link": "https://join.app.net/from/notareallink", }, "meta": { "code": 200 @@ -299,4 +300,4 @@ Returns a list of User tokens corresponding to an app token. Must be requested u "more": false } } -~~~ \ No newline at end of file +~~~ From f0de4ce0f36d6cad155aeca9bcdf57c208047aff Mon Sep 17 00:00:00 2001 From: Lewis Ellis Date: Tue, 11 Jun 2013 14:56:58 -0700 Subject: [PATCH 078/231] Derived filename docs --- content/docs/resources/file/content.md | 4 ++-- content/docs/resources/file/index.md | 12 +++++++----- layouts/partials/endpoints/file.md | 12 ++++++++++++ lib/sample_objects.rb | 2 ++ 4 files changed, 23 insertions(+), 7 deletions(-) diff --git a/content/docs/resources/file/content.md b/content/docs/resources/file/content.md index d9ec308..fb761f1 100644 --- a/content/docs/resources/file/content.md +++ b/content/docs/resources/file/content.md @@ -23,7 +23,7 @@ This endpoint will return a 302 Redirect to a temporary URL for the content of t ## Set File content -Set the content for an incomplete File. The content type for this request must be the content type of the file you are uploading. +Set the content for an incomplete File. The content type for this request must be the content type of the file you are uploading. This endpoint can optionally accept a header field `x-adn-filename` to set the File's name. This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/docs/resources/file/#limits). @@ -63,7 +63,7 @@ This endpoint will return a 302 Redirect to a temporary URL for the content of t ## Set Derived File content -Set the content for a derived file of an incomplete File. The content type for this request must be the content type of the file you are uploading. +Set the content for a derived file of an incomplete File. The content type for this request must be the content type of the file you are uploading. This endpoint can optionally accept a header field `x-adn-filename` to set the File's name. This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this derived file. For more information, see [file storage limits](/docs/resources/file/#limits). diff --git a/content/docs/resources/file/index.md b/content/docs/resources/file/index.md index 474d9ab..5fef1db 100644 --- a/content/docs/resources/file/index.md +++ b/content/docs/resources/file/index.md @@ -97,7 +97,7 @@ A file uploaded by a User and hosted by App.net.     - + @@ -189,6 +189,7 @@ Derived files will include the keys shown in the example below. Please see [the ~~~js "image_thumb_200s": { + "name": "filename_image_thumb_200s.png" "mime_type": "image/png", "sha1": "be91cb06d69df13bb103a359ce70cf9fba31234a", "size": 33803, @@ -221,11 +222,11 @@ Users may include their own derived files when uploading a file with the followi If you're [creating a complete file](/docs/resources/file/lifecycle/#create-a-file), you can specify custom derived files by including a multipart segment for each custom derived file with the key specified in the name field. For example: - curl -k -H 'Authorization: BEARER ...' https://alpha-api.app.net/stream/0/files -X POST -F 'type=com.example.test' -F "content=@filename.png;type=image/png" -F "derived_key1=@derived_file1.png;type=image/png" -F "derived_key2=@derived_file2.png;type=image/png" + curl -k -H 'Authorization: BEARER ...' https://alpha-api.app.net/stream/0/files -X POST -F 'type=com.example.test' -F "content=@filename.png;type=image/png" -F "derived_key1=@derived_file1.png;type=image/png" -F "derived_key2=@derived_file2.png;type=image/png;filename=overridden.png" ##### Custom derived files with an incomplete file -If you've [created a file](/docs/resources/file/lifecycle/#create-a-file) without any content, you can upload custom derived files in subsequent requests until you complete the file. For example: +If you've [created a file](/docs/resources/file/lifecycle/#create-a-file) without any content, you can upload custom derived files in subsequent requests until you complete the file. Either the PUT or POST endpoint can be used. For example: 1. Create an incomplete file: @@ -233,8 +234,9 @@ If you've [created a file](/docs/resources/file/lifecycle/#create-a-file) withou 2. Add custom derived files: - curl -k -H 'Authorization: BEARER ...' https://alpha-api.app.net/stream/0/files/{FILE_ID}/content/{DERIVED_KEY1} -H 'Content-Type: image/png' -X PUT --data-binary @derived_file1.png - curl -k -H 'Authorization: BEARER ...' https://alpha-api.app.net/stream/0/files/{FILE_ID}/content/{DERIVED_KEY2} -H 'Content-Type: image/png' -X PUT --data-binary @derived_file2.png + curl -k -H 'Authorization: BEARER ...' https://alpha-api.app.net/stream/0/files/{FILE_ID}/content/{DERIVED_KEY1} -H 'Content-Type: image/png' -H 'x-adn-filename: filename.png' -X PUT --data-binary @derived_file1.png + + curl -k -H 'Authorization: BEARER ...' https://alpha-api.app.net/stream/0/files/{FILE_ID}/{DERIVED_KEY2} -H 'Content-Type: multipart/form-data' -X POST -F 'type=com.example.test' -F "content=@test.txt;filename=testname.txt" 3. Complete the file: diff --git a/layouts/partials/endpoints/file.md b/layouts/partials/endpoints/file.md index 1b86c3b..30cc7a4 100644 --- a/layouts/partials/endpoints/file.md +++ b/layouts/partials/endpoints/file.md @@ -14,6 +14,12 @@ + + + + + + @@ -56,5 +62,11 @@ + + + + + +
    Name
    name stringThe user provided name of the File. All Unicode characters allowed. Maximum length 255 characters.The user provided name of the File. If no name is provided for a Derived File, it will assume a name of the form filename_derivedkey.ext whenever its root File's name is present. All Unicode characters allowed. Maximum length 255 characters.
    public/stream/0/files User
    Create a Derived FilePOST/stream/0/files/[file_id]/[derived_key]User
    Retrieve a File GET/stream/0/files/[file_id]/content User
    Set Derived File contentPUT/stream/0/files/[file_id]/content/[derived_key]User
    diff --git a/lib/sample_objects.rb b/lib/sample_objects.rb index 83242aa..291ab47 100644 --- a/lib/sample_objects.rb +++ b/lib/sample_objects.rb @@ -49,6 +49,7 @@ def paginated_response(key, &block) "width" => 200, "height" => 200, }, + "name" => "filename_image_thumb_200s.png", "mime_type" => "image/png", "sha1" => "be91cb06d69df13bb103a359ce70cf9fba31234a", "size" => 33803, @@ -60,6 +61,7 @@ def paginated_response(key, &block) "width" => 600, "height" => 800, }, + "name" => "filename_image_thumb_960r.png", "mime_type" => "image/png", "size" => 140173, "sha1" => "57004b55119002f551be5b9f2d5439dd4ad1234a", From 4e92ff1f48592a658deceb3b88b19f7a271ae4b4 Mon Sep 17 00:00:00 2001 From: Lewis Ellis Date: Tue, 11 Jun 2013 15:08:21 -0700 Subject: [PATCH 079/231] Derived file wording tweak --- content/docs/resources/file/content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/file/content.md b/content/docs/resources/file/content.md index fb761f1..87377e5 100644 --- a/content/docs/resources/file/content.md +++ b/content/docs/resources/file/content.md @@ -63,7 +63,7 @@ This endpoint will return a 302 Redirect to a temporary URL for the content of t ## Set Derived File content -Set the content for a derived file of an incomplete File. The content type for this request must be the content type of the file you are uploading. This endpoint can optionally accept a header field `x-adn-filename` to set the File's name. +Set the content for a derived file of an incomplete File. The content type for this request must be the content type of the file you are uploading. This endpoint can optionally accept a header field `x-adn-filename` to set the Derived File's name. This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this derived file. For more information, see [file storage limits](/docs/resources/file/#limits). From e277b3dac461fa9574b216ae72db356cb8c2cd87 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 17 Jun 2013 12:57:08 -0700 Subject: [PATCH 080/231] Migrate stream -> app-stream --- Rules | 8 +++++ config.yaml | 33 +++++++++++-------- .../resources/{stream => app-stream}/index.md | 22 +++++-------- .../{stream => app-stream}/lifecycle.md | 20 +++++------ content/docs/resources/filter/index.md | 2 +- content/docs/resources/interaction/index.md | 2 +- layouts/default.html | 4 +-- layouts/partials/endpoints/stream.md | 14 ++++---- layouts/redirect.html.erb | 12 +++++++ lib/redirector.rb | 24 ++++++++++++++ 10 files changed, 93 insertions(+), 48 deletions(-) rename content/docs/resources/{stream => app-stream}/index.md (90%) rename content/docs/resources/{stream => app-stream}/lifecycle.md (81%) create mode 100644 layouts/redirect.html.erb create mode 100644 lib/redirector.rb diff --git a/Rules b/Rules index d2c40bc..66132c2 100644 --- a/Rules +++ b/Rules @@ -13,6 +13,14 @@ # item, use the pattern “/about/*/”; “/about/*” will also select the parent, # because “*” matches zero or more characters. +# This redirect stuff is inspired by https://gist.github.com/maxim/1782458 +preprocess do + Redirector.generate(config[:redirects], items) +end + +compile '/docs/resources/stream/*' do +end + compile '/static/*' do end diff --git a/config.yaml b/config.yaml index 520fae9..d11f7dd 100644 --- a/config.yaml +++ b/config.yaml @@ -70,17 +70,22 @@ data_sources: # Configuration for the “watch” command, which watches a site for changes and # recompiles if necessary. watcher: - # A list of directories to watch for changes. When editing this, make sure - # that the “output/” and “tmp/” directories are _not_ included in this list, - # because recompiling the site will cause these directories to change, which - # will cause the site to be recompiled, which will cause these directories - # to change, which will cause the site to be recompiled again, and so on. - dirs_to_watch: [ 'content', 'layouts', 'lib' ] - - # A list of single files to watch for changes. As mentioned above, don’t put - # any files from the “output/” or “tmp/” directories in here. - files_to_watch: [ 'config.yaml', 'Rules' ] - - # When to send notifications (using Growl or notify-send). - notify_on_compilation_success: true - notify_on_compilation_failure: true + # A list of directories to watch for changes. When editing this, make sure + # that the “output/” and “tmp/” directories are _not_ included in this list, + # because recompiling the site will cause these directories to change, which + # will cause the site to be recompiled, which will cause these directories + # to change, which will cause the site to be recompiled again, and so on. + dirs_to_watch: [ 'content', 'layouts', 'lib' ] + + # A list of single files to watch for changes. As mentioned above, don’t put + # any files from the “output/” or “tmp/” directories in here. + files_to_watch: [ 'config.yaml', 'Rules' ] + + # When to send notifications (using Growl or notify-send). + notify_on_compilation_success: true + notify_on_compilation_failure: true + +redirects: + # format is current url, then list of old alias + - /docs/resources/app-stream/: + - /docs/resources/stream/ diff --git a/content/docs/resources/stream/index.md b/content/docs/resources/app-stream/index.md similarity index 90% rename from content/docs/resources/stream/index.md rename to content/docs/resources/app-stream/index.md index 2536be8..a71c231 100644 --- a/content/docs/resources/stream/index.md +++ b/content/docs/resources/app-stream/index.md @@ -1,15 +1,15 @@ --- -title: "Stream" +title: "App Stream" --- -# Stream +# App Stream <%= render 'partials/object-tab' %> * TOC {:toc} -A customized view of the the events happening on App.net that is streamed to the client instead of polling. +A customized view of the global events happening on App.net that is streamed to the client instead of polling. ~~~ js { @@ -82,21 +82,17 @@ A customized view of the the events happening on App.net that is streamed to the ## Basic Use -A Stream is a real-time, ordered collection of objects. An object will always be formatted in a [response envelope](/docs/basics/responses/#response-envelope). The ```data``` key will always contain the object. Some actions (like following a user) will contain extra information in the ```meta``` key. +An App Stream contains all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/docs/authentication/flows/app-access-token/)**. You can create up to 5 app streams per App token. An App Stream can only be used on a server (where the App token can be kept secret). -There will be three different kinds of Streams, but they all follow the same pattern: +Each object in the App Stream will be formatted in a [response envelope](/docs/basics/responses/#response-envelope). The ```data``` key will always contain the object. Some actions (like following a user) will contain extra information in the ```meta``` key. -* Public stream (available now): A Stream containing all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/docs/authentication/flows/app-access-token/)**. You can create up to 5 public streams per App token. - -* User stream (coming soon): A Stream for a single User's view of App.net. This is a Stream version of the [Retrieve a User's personalized stream](/docs/resources/post/streams/#retrieve-a-users-personalized-stream) endpoint. It is very useful for client based Apps that need a single User's Stream. **It must be accessed with a User access token**. - -* App stream (coming soon): A Stream for Apps to request multiple Users Streams at once. It is very useful for server based Apps that need the streams of lots of users. **It must be accessed with an App access token**. +If you would like a realtime stream of an individual user's view of App.net, please use a [User Stream](/docs/resources/user-stream). Since memory and bandwidth is not unlimited, each Stream has associated limits. App.net maintains a buffer of objects to send to a client, but if that buffer fills, your Stream will be disconnected. Please ensure that you are only requesting streams of data that you can actually process. ## Filters -Streams will give you lots of data, much of which your application may not want. A [Filter](/docs/resources/filter/) can be passed to the [stream creation endpoint](/docs/resources/stream/lifecycle/#create-a-stream) to control what objects are actually delivered to your App by our servers. +Streams will give you lots of data, much of which your application may not want. A [Filter](/docs/resources/filter/) can be passed to the [stream creation endpoint](/docs/resources/app-stream/lifecycle/#create-a-stream) to control what objects are actually delivered to your App by our servers. ## Response Format @@ -201,7 +197,7 @@ as a key in the object so it is easy to distinguish from a Post. ## Notifications -One of the main uses of the Streaming API is to send notifications to users about what is happening on App.net. When you run a notification service, you need to respect a user's [muting](/docs/resources/user/muting/) and [blocking](/docs/resources/user/blocking/) preferences and whether that event came from a [bot account](/docs/resources/user/#user-fields). If you're sending ["standard" notifications](#standard-notifications), App.net provides some information with each streaming event to make this easier. If you'd like to do something besides the standard notifications, App.net provides some [advanced guidance](#advanced-notifications). +One of the main uses of an App Stream is to send notifications to users about what is happening on App.net. When you run a notification service, you need to respect a user's [muting](/docs/resources/user/muting/) and [blocking](/docs/resources/user/blocking/) preferences and whether that event came from a [bot account](/docs/resources/user/#user-fields). If you're sending ["standard" notifications](#standard-notifications), App.net provides some information with each streaming event to make this easier. If you'd like to do something besides the standard notifications, App.net provides some [advanced guidance](#advanced-notifications). ### Standard Notifications @@ -239,7 +235,7 @@ If you'd like to do complex notifications that aren't possible with the [standar ## Sample stream objects -A Stream can listen for the following object types: +An App Stream can listen for the following object types: * [post](#post): Sent for new posts, replies, reposts, and post deletions * [star](#star): Sent when a user stars a post diff --git a/content/docs/resources/stream/lifecycle.md b/content/docs/resources/app-stream/lifecycle.md similarity index 81% rename from content/docs/resources/stream/lifecycle.md rename to content/docs/resources/app-stream/lifecycle.md index 9f5c3cb..d653e95 100644 --- a/content/docs/resources/stream/lifecycle.md +++ b/content/docs/resources/app-stream/lifecycle.md @@ -1,17 +1,17 @@ --- -title: "Stream Lifecycle" +title: "App Stream Lifecycle" --- -# Stream Lifecycle +# App Stream Lifecycle * TOC {:toc} ## Create a Stream -Create a [Stream](/docs/resources/stream/) for the current token. +Create a [Stream](/docs/resources/app-stream/) for the current token. -Send a JSON document that matches the [stream schema](/docs/resources/stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. +Send a JSON document that matches the [stream schema](/docs/resources/app-stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. You can create up to 5 streams per App token. @@ -19,7 +19,7 @@ You can create up to 5 streams per App token. #### POST Data -A JSON object representing the stream to create. See [the stream object](/docs/resources/stream/) for more information. Specify ```filter_id``` instead of ```filter``` if you want to filter this stream. (Omit the ```id``` and ```endpoint``` parameters). +A JSON object representing the stream to create. See [the stream object](/docs/resources/app-stream/) for more information. Specify ```filter_id``` instead of ```filter``` if you want to filter this stream. (Omit the ```id``` and ```endpoint``` parameters). #### Example @@ -61,7 +61,7 @@ A JSON object representing the stream to create. See [the stream object](/docs/r ## Retrieve a Stream -Returns a specific [Stream](/docs/resources/stream/) object. +Returns a specific [Stream](/docs/resources/app-stream/) object. <%= endpoint "GET", "streams/[stream_id]", "App" %> @@ -104,7 +104,7 @@ Returns a specific [Stream](/docs/resources/stream/) object. ## Get current token's Streams -Return the [Streams](/docs/resources/stream/) for the current token. +Return the [Streams](/docs/resources/app-stream/) for the current token. <%= endpoint "GET", "streams", "App" %> @@ -154,7 +154,7 @@ Return the [Streams](/docs/resources/stream/) for the current token. ## Update a Stream -Update a [Stream](/docs/resources/stream/). You can update a Stream by PUTing a JSON document that matches the [stream schema](/docs/resources/stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. +Update a [Stream](/docs/resources/app-stream/). You can update a Stream by PUTing a JSON document that matches the [stream schema](/docs/resources/app-stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. <%= endpoint "PUT", "streams/[stream_id]", "App" %> @@ -203,7 +203,7 @@ Update a [Stream](/docs/resources/stream/). You can update a Stream by PUTing a ## Delete a Stream -Delete a [Stream](/docs/resources/stream/). The Stream must belong to the current User. It returns the deleted Stream on success. +Delete a [Stream](/docs/resources/app-stream/). The Stream must belong to the current User. It returns the deleted Stream on success. *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* @@ -248,7 +248,7 @@ Delete a [Stream](/docs/resources/stream/). The Stream must belong to the curren ## Delete all of the current user's Streams -Delete all [Streams](/docs/resources/stream/) for the current token. It returns the deleted Streams on success. +Delete all [Streams](/docs/resources/app-stream/) for the current token. It returns the deleted Streams on success. *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* diff --git a/content/docs/resources/filter/index.md b/content/docs/resources/filter/index.md index 8cc658a..81a93f8 100644 --- a/content/docs/resources/filter/index.md +++ b/content/docs/resources/filter/index.md @@ -9,7 +9,7 @@ title: "Filter" * TOC {:toc} -A Filter restricts a stream of messages on the server side so your client only sees what it's interested in. [Streams](/docs/resources/stream/) are currently the only way to use filters right now. +A Filter restricts a stream of messages on the server side so your client only sees what it's interested in. [Streams](/docs/resources/app-stream/) are currently the only way to use filters right now. ~~~ js { diff --git a/content/docs/resources/interaction/index.md b/content/docs/resources/interaction/index.md index d51b127..86ac28f 100644 --- a/content/docs/resources/interaction/index.md +++ b/content/docs/resources/interaction/index.md @@ -95,7 +95,7 @@ List all the [Interactions](/docs/resources/interaction/) other users have had w > Note: you can only request this list for the current user. -> Note: although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/docs/resources/stream/) to monitor the global feed for relevant activity. +> Note: although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/docs/resources/app-stream/) to monitor the global feed for relevant activity. <%= endpoint "GET", "users/me/interactions", "User" %> diff --git a/layouts/default.html b/layouts/default.html index 8014b4d..6e026f9 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -109,9 +109,9 @@
  • Lifecycle
  • Content
    • -
  • Stream
    • +
  • App Stream
  • Filter
      • diff --git a/layouts/partials/endpoints/stream.md b/layouts/partials/endpoints/stream.md index 7672e1b..e8ab28e 100644 --- a/layouts/partials/endpoints/stream.md +++ b/layouts/partials/endpoints/stream.md @@ -9,37 +9,37 @@
    Create a StreamCreate an App Stream POST /stream/0/streams App
    Retrieve a StreamRetrieve an App Stream GET /stream/0/streams/[stream_id] App
    Update a StreamUpdate an App Stream PUT /stream/0/streams/[stream_id] App
    Delete a StreamDelete an App Stream DELETE /stream/0/streams/[stream_id] App
    Retrieve all Streams for the current TokenRetrieve all App Streams for the current Token GET /stream/0/streams App
    Delete all Streams for the current TokenDelete all App Streams for the current Token DELETE /stream/0/streams App
    + + + + + + + + + + + + + + + + + + + + + + +
    DescriptionMethodPathToken
    Delete a User StreamDELETE/stream/0/users/me/streams/[connection_id]User
    Delete a User Stream subscriptionDELETE/stream/0/users/me/streams/[connection_id]/[subscription_id]User
    \ No newline at end of file From 9803d508c651464f4290756f88b4d1541ac98130 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 17 Jun 2013 16:00:49 -0700 Subject: [PATCH 082/231] User stream docs cleanup --- content/docs/resources/user-stream/index.md | 24 +++++++++---------- .../docs/resources/user-stream/lifecycle.md | 5 ++-- content/index.md | 1 + 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/content/docs/resources/user-stream/index.md b/content/docs/resources/user-stream/index.md index 4a03c8e..6ce8e8a 100644 --- a/content/docs/resources/user-stream/index.md +++ b/content/docs/resources/user-stream/index.md @@ -169,17 +169,17 @@ In general, the User Streams API tries to mimc the format and conventions of the 1. When you receive a message, it will look like: - { - "meta": { - "subscription_ids": ["d3b72b23-f8d7-4108-a4f1-3aaa25328286"], - "min_id": "5675993", - "max_id": "5675993", - "connection_id": "Ne1Rpr4DgmilaYUCe51aoRQpCDei14Aw", - "more": false - }, - "data": [ - ... posts ... - ] - } + { + "meta": { + "subscription_ids": ["d3b72b23-f8d7-4108-a4f1-3aaa25328286"], + "min_id": "5675993", + "max_id": "5675993", + "connection_id": "Ne1Rpr4DgmilaYUCe51aoRQpCDei14Aw", + "more": false + }, + "data": [ + ... posts ... + ] + } <%= render 'partials/endpoints-tab', :for => "user-stream" %> diff --git a/content/docs/resources/user-stream/lifecycle.md b/content/docs/resources/user-stream/lifecycle.md index d746ad7..c68ae8e 100644 --- a/content/docs/resources/user-stream/lifecycle.md +++ b/content/docs/resources/user-stream/lifecycle.md @@ -19,7 +19,7 @@ Delete a [User Stream](/docs/resources/user-stream/). The User Stream must belon ["connection_id", "The connection id of the User Stream to delete."] ]%> -#### Example +### Example > DELETE https://alpha-api.app.net/stream/0/streams/sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf > @@ -37,7 +37,8 @@ Delete a subscription of a [User Stream](/docs/resources/user-stream/). The User ["connection_id", "The connection id of the User Stream the subscription belongs to."], ["subscription_id", "The subscription id of the subscription to cancel"] ]%> -#### Example + +### Example > DELETE https://alpha-api.app.net/stream/0/streams/sxousNClc4Cq12du3f6GTZXNUvaHoJnFnjdOt6fH2xhJolPdDfR3rOxxjdPfPOIf/bf42ca05-e67e-4e26-8bd0-8b042dd5b04c > diff --git a/content/index.md b/content/index.md index 01d6a07..8fba412 100644 --- a/content/index.md +++ b/content/index.md @@ -16,6 +16,7 @@ To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adna {::options parse_block_html="true" /}
    +* (6/17/2013) **Introducing the User Stream API** — check out the documentation for [User Streams](/docs/resources/user-stream/). * (2/5/2013) **Introducing the Place API** — check out the documentation for [Places](/docs/resources/place/). * (1/28/2013) **Introducing the File API** — check out the documentation for [Files](/docs/resources/file/). * (12/13/2012) **Introducing the Messaging API** — check out the documentation for [Channels](/docs/resources/channel/) and [Messages](/docs/resources/message/) and the [App.net Messaging overview](/docs/basics/messaging/). From 3f1b0263211a8157a3b403433b8f4123a3e7f429 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 24 Jun 2013 16:38:15 -0700 Subject: [PATCH 083/231] Add options for auto_delete and parse_links --- content/docs/meta/entities.md | 18 +++++++++++++++++- content/docs/resources/app-stream/index.md | 4 +++- content/docs/resources/app-stream/lifecycle.md | 2 ++ content/docs/resources/user-stream/index.md | 4 ++++ .../docs/resources/user-stream/lifecycle.md | 2 ++ 5 files changed, 28 insertions(+), 2 deletions(-) diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index 3d355e3..b1007d2 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -198,7 +198,23 @@ Entities are automatically extracted from the post text but there are 2 cases wh ### Links with custom anchor text -If you'd like to provide a link without including the entire URL in your post text or user description, you can specify a custom link at Post creation time or User update time. **If you include a list of links in your Post — even an empty list — App.net will not extract any links on the server.** Mentions and hashtags will still be extracted and your provided links must not overlap with these extracted entities. So you **cannot** have a custom link around a hashtag or mention. +If you'd like to provide a link without including the entire URL in your post text or user description, you can specify a custom link at Post creation time or User update time. **If you include a list of links in your Post — even an empty list — App.net by default will not extract any links on the server.** Mentions and hashtags will still be extracted and your provided links must not overlap with these extracted entities. So you **cannot** have a custom link around a hashtag or mention. If you want App.net to still extract links, you can pass the `parse_links: true` option to App.net. User provided links will take precedence over any links App.net detects. For example, the following JSON will create a post to 2 links 1) the parsed link to App.net and 2) the user provided link to the App.net blog: + +~~~js +{ + "text": "The official App.net blog is here", + "entities": { + "links": [ + { + "pos": 29, + "len": 4, + "url": "http://blog.app.net/" + } + ], + "parse_links": true + } +} +~~~ To prevent phishing, any link where the anchor text differs from the destination domain will be followed by the domain of the link target. These extra characters added by App.net to the `text` field will not count against the 256 character Post limit. In this case, App.net will also add the [`amended_len`](#links) field that includes the length of the complete entity and added anti-phishing text. This will make it easier for apps to customize how the anti-phishing protection looks in their apps. **When rendering links in your app, you must show users an indication of where they will end up.** diff --git a/content/docs/resources/app-stream/index.md b/content/docs/resources/app-stream/index.md index ac77280..7b9a260 100644 --- a/content/docs/resources/app-stream/index.md +++ b/content/docs/resources/app-stream/index.md @@ -82,7 +82,9 @@ A customized view of the global events happening on App.net that is streamed to ## Basic Use -An App Stream contains all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/docs/authentication/flows/app-access-token/)**. You can create up to 5 app streams per App token. An App Stream can only be used on a server (where the App token can be kept secret). + curl -i + +An App Stream contains all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/docs/authentication/flows/app-access-token/)**. You can create up to 5 app streams per App token. An App Stream can only be used on a server (where the App token can be kept secret). If you would like your stream to be automatically deleted when you disconnect from your app stream, add the `auto_delete=1` query string parameter when connecting to a stream. Each object in the App Stream will be formatted in a [response envelope](/docs/basics/responses/#response-envelope). The ```data``` key will always contain the object. Some actions (like following a user) will contain extra information in the ```meta``` key. diff --git a/content/docs/resources/app-stream/lifecycle.md b/content/docs/resources/app-stream/lifecycle.md index d653e95..f8422db 100644 --- a/content/docs/resources/app-stream/lifecycle.md +++ b/content/docs/resources/app-stream/lifecycle.md @@ -205,6 +205,8 @@ Update a [Stream](/docs/resources/app-stream/). You can update a Stream by PUTin Delete a [Stream](/docs/resources/app-stream/). The Stream must belong to the current User. It returns the deleted Stream on success. +If you'd like your app stream to be automatically deleted when you disconnect from it, please add the [`auto_delete=1`](/docs/resources/user-stream/#limits) query string parameter when you connect to your app stream. + *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "streams/[stream_id]", "App" %> diff --git a/content/docs/resources/user-stream/index.md b/content/docs/resources/user-stream/index.md index 6ce8e8a..2589ffe 100644 --- a/content/docs/resources/user-stream/index.md +++ b/content/docs/resources/user-stream/index.md @@ -79,6 +79,10 @@ Ordering is not guaranteed for events delivered on streams, but we aim to have t * Each user token can create at most 5 User Streams * Each User Stream can have at most 50 subscriptions. The same endpoint can be subscribed to multiple times. +To avoid thinking about limits, you can create User streams that automatically delete themselves once you disconnect from them. If you use this option, you will always have to recreate your subscriptions from scratch. To enable this, add the `auto_delete=1` query string parameter when connecting to a stream. + + curl -i -H 'Authorization: BEARER ...' "https://stream-channel.app.net/stream/user?auto_delete=1" + ## Subscription options The App.net API accepts many query string parameters (`include_deleted`, `include_html`, etc) to customize and filter the data returned. These query string parameters are also respected by the User Streaming API with an important caveat. "Display options" are a connection-wide property and must be specified when a User Stream is created. "Filter options" are provided per subscription. diff --git a/content/docs/resources/user-stream/lifecycle.md b/content/docs/resources/user-stream/lifecycle.md index c68ae8e..53113ab 100644 --- a/content/docs/resources/user-stream/lifecycle.md +++ b/content/docs/resources/user-stream/lifecycle.md @@ -11,6 +11,8 @@ title: "User Stream Lifecycle" Delete a [User Stream](/docs/resources/user-stream/). The User Stream must belong to the current token. It disconnects any sockets with this User Stream open and returns an HTTP 204 No Content on success. +If you'd like your user stream to be automatically deleted when you disconnect from it, please add the [`auto_delete=1`](/docs/resources/user-stream/#limits) query string parameter when you create the user stream. + *Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "users/me/streams/[connection_id]", "User" %> From 67778e72a0c77adc184c407f52bbc16fcdb8c076 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Tue, 2 Jul 2013 17:22:48 -0700 Subject: [PATCH 084/231] Adding in new authorization button text --- content/docs/authentication/flows/web.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/content/docs/authentication/flows/web.md b/content/docs/authentication/flows/web.md index 9567173..9f32449 100644 --- a/content/docs/authentication/flows/web.md +++ b/content/docs/authentication/flows/web.md @@ -11,7 +11,7 @@ title: "Web Flows" This is the easiest way to get an access token—we recommend it to most users of the API. If you're writing an app on a server using a language like Ruby, Python, PHP, Java, etc. you should use this flow. -**You must keep your client_secret confidential**. That means that you may not include it in the source code or binary of an application that you ship to end-users, even in obscured form. +**You must keep your client_secret confidential**. That means that you may not include it in the source code or binary of an application that you ship to end-users, even in obscured form. 1. Direct the user that you want to authenticate to this URL: @@ -74,3 +74,19 @@ If you're building a client-side Javascript app or a mobile app that doesn't hav > If you included a query string in your redirect URI, the `code` parameter will be appended. Likewise, the scheme of your redirect URI will be respected, though we strongly recommend sending all traffic over HTTPS. The access_token will be appended to the URI in the fragment section, encoded as if it were a query string. Your client-side code should parse this for the access_token. + + +## Authorize With App.net Button + +The Authorize with App.net Button is the easiest way to let people sign into and authorize your web app with their App.net credentials. If they don’t have an App.net account, this button will allow new users to create an account and then authorize your app. + +To implement the button replace the variables inside the brackets in this snippet and then paste it into your HTML where you want the button to show up. + + Authorize with App.net + + +If you want to see a live example of this button you can checkout [Patter](http://patter-app.net). + +We suggest that you put copy like this near the button to explain to the user what is going to happen: + +>An App.net account is required to use [Your App Name]. You can create an account and sign in with this button. From 19ca3e8920924030e00807b024996f5c456363ea Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 3 Jul 2013 14:34:22 -0700 Subject: [PATCH 085/231] cut this for now --- content/docs/authentication/flows/web.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/authentication/flows/web.md b/content/docs/authentication/flows/web.md index 9f32449..8704332 100644 --- a/content/docs/authentication/flows/web.md +++ b/content/docs/authentication/flows/web.md @@ -85,7 +85,6 @@ To implement the button replace the variables inside the brackets in this snippe Authorize with App.net -If you want to see a live example of this button you can checkout [Patter](http://patter-app.net). We suggest that you put copy like this near the button to explain to the user what is going to happen: From c40ccd993a9f13e585a48e07004858ddb0ea340d Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Mon, 8 Jul 2013 15:53:41 -0700 Subject: [PATCH 086/231] Breaking up the auth button section --- content/docs/authentication/flows/web.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/docs/authentication/flows/web.md b/content/docs/authentication/flows/web.md index 8704332..63b8b7b 100644 --- a/content/docs/authentication/flows/web.md +++ b/content/docs/authentication/flows/web.md @@ -80,11 +80,14 @@ If you're building a client-side Javascript app or a mobile app that doesn't hav The Authorize with App.net Button is the easiest way to let people sign into and authorize your web app with their App.net credentials. If they don’t have an App.net account, this button will allow new users to create an account and then authorize your app. +### Implementation + To implement the button replace the variables inside the brackets in this snippet and then paste it into your HTML where you want the button to show up. Authorize with App.net +### Best Practices We suggest that you put copy like this near the button to explain to the user what is going to happen: From a1f1d05c7e0a19c77d7087c521dc22cacf740426 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Mon, 8 Jul 2013 17:52:17 -0700 Subject: [PATCH 087/231] Updating copy on authorize with app.net --- content/docs/authentication/flows/web.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/content/docs/authentication/flows/web.md b/content/docs/authentication/flows/web.md index 63b8b7b..47e0aec 100644 --- a/content/docs/authentication/flows/web.md +++ b/content/docs/authentication/flows/web.md @@ -78,17 +78,21 @@ If you're building a client-side Javascript app or a mobile app that doesn't hav ## Authorize With App.net Button -The Authorize with App.net Button is the easiest way to let people sign into and authorize your web app with their App.net credentials. If they don’t have an App.net account, this button will allow new users to create an account and then authorize your app. +The Authorize with App.net Button is the easiest way to let people sign into and authorize your web app with their App.net credentials. If they don't have an App.net account, this button will allow new users to create an account and then authorize your app. ### Implementation -To implement the button replace the variables inside the brackets in this snippet and then paste it into your HTML where you want the button to show up. +To implement the button on your site, you must: - Authorize with App.net - +1. Replace the variables inside the brackets +1. Copy and paste the snippet below into your HTML where you want the button to show up + + +
    <a href='http://github.com/[Your%20Normal%20Authentication%20URL]' class='adn-button' data-type='authorize' data-width="145" data-height="22" data-client-id='[your client ID]' data-response-type='[token, or code]' data-scope='[scopes separated by spaces]' >Authorize with App.net</a><script>(function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src='http://d2zh9g63fcvyrq.cloudfront.net/adn.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'adn-button-js'));</script>
    ### Best Practices -We suggest that you put copy like this near the button to explain to the user what is going to happen: +We suggest that you put the following copy directly above or below the button: + + An App.net account is required to use [Your App Name]. You can create an account and sign in by clicking this button. ->An App.net account is required to use [Your App Name]. You can create an account and sign in with this button. From aff46bc65321841ea2955666b6b91423c639a89a Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 8 Jul 2013 16:14:20 -0700 Subject: [PATCH 088/231] Add User sample object and clean up the user api docs --- .../docs/resources/channel/subscriptions.md | 71 +---- content/docs/resources/file/lifecycle.md | 2 +- content/docs/resources/file/lookup.md | 1 - content/docs/resources/token/index.md | 102 +------ content/docs/resources/user/blocking.md | 199 +------------ content/docs/resources/user/following.md | 268 ++---------------- content/docs/resources/user/index.md | 85 ++---- content/docs/resources/user/lookup.md | 126 +------- content/docs/resources/user/muting.md | 192 +------------ .../docs/resources/user/post-interactions.md | 136 +-------- content/docs/resources/user/profile.md | 221 ++------------- lib/sample_objects.rb | 119 +++++++- 12 files changed, 215 insertions(+), 1307 deletions(-) diff --git a/content/docs/resources/channel/subscriptions.md b/content/docs/resources/channel/subscriptions.md index e1519d1..1aa7c26 100644 --- a/content/docs/resources/channel/subscriptions.md +++ b/content/docs/resources/channel/subscriptions.md @@ -188,72 +188,11 @@ Retrieve the users who are subscribed to a Channel. > GET https://alpha-api.app.net/stream/0/channels/1/subscribers -~~~ js -{ - "data": [ - { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, - }, - ... - ], - "meta": { - "code": 200, - "max_id": 82, - "min_id": 54, - "more": true - } -} -~~~ +<%= paginated_response(:user) do |h| + h["meta"]["more"] = true + h["meta"]["max_id"] = 82 + h["meta"]["min_id"] = 82 +end %> ## Retrieve user ids subscribed to a Channel diff --git a/content/docs/resources/file/lifecycle.md b/content/docs/resources/file/lifecycle.md index 958089e..ba58fc9 100644 --- a/content/docs/resources/file/lifecycle.md +++ b/content/docs/resources/file/lifecycle.md @@ -92,7 +92,7 @@ This endpoint currently works identically for the `PUT` and `PATCH` HTTP methods > > DATA {"name": "updated_filename.jpg"} -<%= response(:file) {|h| h["data"]["name"] = "updated_filename.jpg"; h} %> +<%= response(:file) {|h| h["data"]["name"] = "updated_filename.jpg"} %> ## Delete a File diff --git a/content/docs/resources/file/lookup.md b/content/docs/resources/file/lookup.md index 09b65d6..d0b0ce9 100644 --- a/content/docs/resources/file/lookup.md +++ b/content/docs/resources/file/lookup.md @@ -49,7 +49,6 @@ Returns multiple Files requested by id. At most 200 files can be requested. File second = h["data"][0].clone() second["id"] = "2" h["data"].unshift(second) - h } %> ## Retrieve my Files diff --git a/content/docs/resources/token/index.md b/content/docs/resources/token/index.md index 0c4fd50..9dfcff5 100644 --- a/content/docs/resources/token/index.md +++ b/content/docs/resources/token/index.md @@ -70,56 +70,7 @@ Requested with a user access token: }, "user": { "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, + ... }, "invite_link": "https://join.app.net/from/notareallink", }, @@ -167,56 +118,7 @@ Requested with a user access token: }, "user": { "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, + ... } }, "meta": { diff --git a/content/docs/resources/user/blocking.md b/content/docs/resources/user/blocking.md index 1898a0a..8a29192 100644 --- a/content/docs/resources/user/blocking.md +++ b/content/docs/resources/user/blocking.md @@ -25,67 +25,10 @@ In most cases, [muting a user](/docs/resources/user/muting/#mute-a-user) is prob > POST https://alpha-api.app.net/stream/0/users/1/block -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_blocked": true, - "you_follow": false, - "you_muted": false - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user) do |h| + h["data"]["you_blocked"] = true + h["data"]["you_follow"] = false +end %> ## Unblock a User @@ -105,67 +48,10 @@ Allow a blocked user to interact with my content. > DELETE https://alpha-api.app.net/stream/0/users/1/block -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_blocked": false, - "you_follow": false, - "you_muted": false, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user) do |h| + h["data"]["you_blocked"] = false + h["data"]["you_follow"] = false +end %> ## List blocked Users @@ -183,71 +69,10 @@ Retrieve a list of blocked users. > GET https://alpha-api.app.net/stream/0/users/me/blocked -~~~ js -{ - "data": [ - { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_blocked": true, - "you_follow": false, - "you_muted": false, - }, - ... - ], - "meta": { - "code": 200 - } -} -~~~ - +<%= collection_response(:user) do |h| + h["data"][0]["you_blocked"] = true + h["data"][0]["you_follow"] = false +end %> ## Retrieve blocked User IDs for multiple Users diff --git a/content/docs/resources/user/following.md b/content/docs/resources/user/following.md index 4087056..1d2efc3 100644 --- a/content/docs/resources/user/following.md +++ b/content/docs/resources/user/following.md @@ -23,66 +23,9 @@ Returns the User object of the user being fo > POST https://alpha-api.app.net/stream/0/users/1/follow -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user) do |h| + h["data"]["you_follow"] = true +end %> ## Unfollow a User @@ -102,66 +45,9 @@ Returns the User object of the user being un > DELETE https://alpha-api.app.net/stream/0/users/1/follow -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": false, - "you_muted": false, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user) do |h| + h["data"]["you_follow"] = false +end %> ## List users a user is following @@ -181,72 +67,11 @@ Returns a list of User objects the specified > GET https://alpha-api.app.net/stream/0/users/2/following -~~~ js -{ - "data": [ - { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, - }, - ... - ], - "meta": { - "code": 200, - "max_id": "2", - "min_id": "1", - "more": true - } -} -~~~ +<%= paginated_response(:user) do |h| + h["meta"]["more"] = true + h["meta"]["min_id"] = "4621" + h["meta"]["max_id"] = "4621" +end %> ## List users following a user @@ -266,72 +91,11 @@ Returns a list of User objects for users fol > GET https://alpha-api.app.net/stream/0/users/2/followers -~~~ js -{ - "data": [ - { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, - }, - ... - ], - "meta": { - "code": 200, - "max_id": "2", - "min_id": "1", - "more": true - } -} -~~~ +<%= paginated_response(:user) do |h| + h["meta"]["more"] = true + h["meta"]["min_id"] = "2889" + h["meta"]["max_id"] = "2889" +end %> ## List user ids a User is following diff --git a/content/docs/resources/user/index.md b/content/docs/resources/user/index.md index d211c9e..c1b9071 100644 --- a/content/docs/resources/user/index.md +++ b/content/docs/resources/user/index.md @@ -13,72 +13,17 @@ A User is the central object of the App.net APIs. User objects have usernames, f ## Example User object -~~~ js -{ - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "width": 320, - "height": 118, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_blocked": false, - "you_follow": true, - "you_muted": false, - "you_can_subscribe": true, - "verified_domain": "example.com", - "annotations": [ - { - "type": "net.app.core.directory.blog", - "value": { - "url": "http://myawesomeblog.com/" - } - } +<%= json(:user) { |h| + h["annotations"] = [ + { + "type" => "net.app.core.directory.blog", + "value" => { + "url" => "http://myawesomeblog.com/" + } + } ] -} -~~~ + h +} %> ## User fields @@ -221,6 +166,11 @@ A User is the central object of the App.net APIs. User objects have usernames, f boolean Does the user making the request have the ability to subscribe this user to channels? May be omitted if this is not an authenticated request. + + you_can_follow + boolean + Does the user making the request have the ability to follow this user? This may be affected by privacy settings or the requesting user's type. May be omitted if this is not an authenticated request. + verified_domain string @@ -231,6 +181,11 @@ A User is the central object of the App.net APIs. User objects have usernames, f list Metadata about the user. See the Annotations documentation. + + canonical_url + string + The URL of the user's detail page on Alpha. + ### Deprecations diff --git a/content/docs/resources/user/lookup.md b/content/docs/resources/user/lookup.md index 585fe39..c67ae5f 100644 --- a/content/docs/resources/user/lookup.md +++ b/content/docs/resources/user/lookup.md @@ -23,66 +23,7 @@ Returns a specific User object. > GET https://alpha-api.app.net/stream/0/users/1 -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user) %> ## Retrieve multiple Users Returns multiple Users requested by id. At most 200 users can be requested. @@ -136,67 +77,6 @@ Search the App.net userbase. #### Example -> GET https://alpha-api.app.net/stream/0/users/search?q=%23mondaynightdanceparty +> GET https://alpha-api.app.net/stream/0/users/search?q=%23api -~~~ js -{ - "data": [ - { - "avatar_image": { - "height": 200, - "url": "https://d2rfichhc2fb9n.cloudfront.net/image/4/sRRkCKVga-subI-q0oTsiuUAoo6ZP-f4g0xneKB89OxKGrmNizM78Qv0p-FKRFekdLWy58o7cl21DQILfGJjQz-GKlisIUWI3ENw4YISVZnDKJM7f359Fuqq3ckhBmWO5xVBWrlIOi3odNtOjPeJdwv70B0", - "width": 200 - }, - "counts": { - "followers": 97, - "following": 58, - "posts": 934, - "stars": 25 - }, - "cover_image": { - "height": 250, - "url": "https://d2rfichhc2fb9n.cloudfront.net/image/4/JeN1azqHPSPuzGtfk07SU7S7Hp4WNYIfiO_CiNxJ_gt9dnx4-ltGJZInJi7-ipXzrokyK7jUtQl8p6g2L6FOIIha9IU_Fm74AIDhftD6XvbGDPUS3s3pKSWGeyDkS28zL-RjyrfQHNpVLsJhgE0L6UuVfao", - "width": 960 - }, - "created_at": "2012-08-10T21:28:45Z", - "description": { - "entities": { - "hashtags": [ - { - "len": 22, - "name": "MondayNightDanceParty", - "pos": 23 - } - ], - "links": [ - { - "len": 13, - "pos": 57, - "text": "s3rv.com/mndp", - "url": "http://s3rv.com/mndp" - } - ], - "mentions": [] - }, - "html": "gamer, dev, debaser\r\n\r\n#MondayNightDanceParty details at s3rv.com/mndp.", - "text": "gamer, dev, debaser\r\n\r\n#MondayNightDanceParty details at s3rv.com/mndp." - }, - "follows_you": true, - "id": "1411", - "is_follower": true, - "is_following": true, - "is_muted": false, - "locale": "en", - "name": "Robert", - "timezone": "America/Chicago", - "type": "human", - "username": "33mhz", - "you_follow": true, - "you_muted": false - } - ], - "meta": { - "code": 200 - } -} -~~~ +<%= collection_response(:user) %> diff --git a/content/docs/resources/user/muting.md b/content/docs/resources/user/muting.md index bae31da..cf1ac63 100644 --- a/content/docs/resources/user/muting.md +++ b/content/docs/resources/user/muting.md @@ -23,66 +23,9 @@ Hide all posts for a User in all streams. *Note: if you still explicitly request > POST https://alpha-api.app.net/stream/0/users/1/mute -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": true, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user) do |h| + h["data"]["you_muted"] = true +end %> ## Unmute a User @@ -102,66 +45,9 @@ Stop hiding all posts for a given user. > DELETE https://alpha-api.app.net/stream/0/users/1/mute -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": false, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user) do |h| + h["data"]["you_muted"] = false +end %> ## List muted Users @@ -179,69 +65,9 @@ Retrieve a list of muted users. > GET https://alpha-api.app.net/stream/0/users/me/muted -~~~ js -{ - "data": [ - { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": true, - }, - ... - ], - "meta": { - "code": 200 - } -} -~~~ +<%= collection_response(:user) do |h| + h["data"][0]["you_muted"] = true +end %> ## Retrieve muted User IDs for multiple Users diff --git a/content/docs/resources/user/post-interactions.md b/content/docs/resources/user/post-interactions.md index 189b84f..de59014 100644 --- a/content/docs/resources/user/post-interactions.md +++ b/content/docs/resources/user/post-interactions.md @@ -23,69 +23,11 @@ List all the Users who have reposted a given Post. > GET https://alpha-api.app.net/stream/0/posts/1/reposters -~~~ js -{ - "data": [ - { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": true, - }, - ... - ], - "meta": { - "code": 200 - } -} -~~~ +<%= paginated_response(:user) do |h| + h["meta"]["min_id"] = "345" + h["meta"]["max_id"] = "345" + h["meta"]["more"] = true +end %> ## List Users who have starred a Post @@ -103,66 +45,8 @@ List all the Users who have starred a given Post. > GET https://alpha-api.app.net/stream/0/posts/1/stars -~~~ js -{ - "data": [ - { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "follows_you": false, - "you_follow": true, - "you_muted": true, - }, - ... - ], - "meta": { - "code": 200 - } -} -~~~ \ No newline at end of file +<%= paginated_response(:user) do |h| + h["meta"]["min_id"] = "1356" + h["meta"]["max_id"] = "1356" + h["meta"]["more"] = true +end %> diff --git a/content/docs/resources/user/profile.md b/content/docs/resources/user/profile.md index d0b38eb..299db30 100644 --- a/content/docs/resources/user/profile.md +++ b/content/docs/resources/user/profile.md @@ -27,51 +27,20 @@ If you want to add or update a User's annotations, you may include the optional > > DATA {"name": "Mark Thurman 2", "locale":"en", "timezone":"US/Central", "description":{"text": "new description"}, "annotations":[{"type": "net.app.core.directory.blog", "value": {"url": "http://mynewblog.com/"}}] -~~~js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman 2", - "description": { - "text": "new description", - "html": "new description", - "entities": {} - }, - "timezone": "US/Central", - "locale": "en", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - "annotations": [ - { - "type": "net.app.core.directory.blog", - "value": "http://mynewblog.com/" - } - ] - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user_self) do |h| + h["data"]["name"] = "Mark Thurman 2" + h["data"]["locale"] = "en_US" + h["data"]["description"]["text"] = "new description" + h["data"]["description"]["html"] = "new description" + h["data"]["description"]["entities"] = {} + h["data"]["timezone"] = "US/Central" + h["data"]["annotations"] = [ + { + "type" => "net.app.core.directory.blog", + "value" => "http://mynewblog.com/" + } + ] +end %> ## Partially Update a User @@ -89,45 +58,9 @@ Updates a subset of a specific user's profile details. You can update a user by > > DATA {"name": "Mark Thurman 2"} -~~~js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman 2", - "description": { - "text": "description", - "html": "description", - "entities": {} - }, - "timezone": "US/Pacific", - "locale": "en", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user_self) do |h| + h["data"]["name"] = "Mark Thurman 2" +end %> ## Retrieve a User's avatar image @@ -181,63 +114,9 @@ Replace a User's avatar image with the uploaded file. The uploaded image Will be > > DATA [MIME encoded image] -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/new_avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user_self) do |h| + h["data"]["avatar_image"]["url"] = "https://example.com/new_avatar_image.jpg" +end %> ## Retrieve a User's cover image @@ -292,60 +171,6 @@ Replace a User's cover image with the uploaded file. The uploaded image must be > > DATA [MIME encoded image] -~~~ js -{ - "data": { - "id": "1", // note this is a string - "username": "mthurman", - "name": "Mark Thurman", - "description": { - "text": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "html": "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", - "entities": { - "mentions": [{ - "name": "appdotnet", - "id": "3", - "pos": 52, - "len": 10 - }], - "hashtags": [{ - "name": "api", - "pos": 70, - "len": 4 - }], - "links": [{ - "text": "teaching you", - "url": "https://github.com/appdotnet/api-spec", - "pos": 29, - "len": 12 - }] - } - }, - "timezone": "US/Pacific", - "locale": "en_US", - "avatar_image": { - "height": 512, - "width": 512, - "url": "https://example.com/avatar_image.jpg", - "is_default": false - }, - "cover_image": { - "height": 118, - "width": 320, - "url": "https://example.com/new_cover_image.jpg", - "is_default": false - }, - "type": "human", - "created_at": "2012-07-16T17:23:34Z", - "counts": { - "following": 100, - "followers": 200, - "posts": 24, - "stars": 76 - }, - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:user_self) do |h| + h["data"]["cover_image"]["url"] = "https://example.com/new_cover_image.jpg" +end %> diff --git a/lib/sample_objects.rb b/lib/sample_objects.rb index 291ab47..d262beb 100644 --- a/lib/sample_objects.rb +++ b/lib/sample_objects.rb @@ -10,14 +10,58 @@ def get_hash(key) h when Array key - else Resources.const_get(key.to_s.upcase).dup() + # deep copy so we can make any overrides we need for our specific use of this hash + else deep_copy(Resources.const_get(key.to_s.upcase)) end end + def json_output(hash) + "~~~js\n" + JSON.pretty_generate(hash) + "\n~~~" + end + def json(key) hash = get_hash(key) - hash = yield hash if block_given? - "~~~js\n" + JSON.pretty_generate(hash) + "\n~~~" + yield hash if block_given? + json_output(hash) + end + + def deep_copy(o) + Marshal.load(Marshal.dump(o)) + end + + def diff_hash(a, b) + (a.keys | b.keys).inject({}) do |diff, k| + if a[k] != b[k] + if a[k].is_a?(Hash) && b[k].is_a?(Hash) + diff[k] = diff_hash(a[k], b[k]) + elsif a[k].is_a?(Array) && b[k].is_a?(Array) + diff[k] = a[k].zip(b[k]).map {|el| diff_hash(el[0], el[1])} + else + diff[k] = [a[k], b[k]] + end + end + diff + end + end + + def parse_hash(data) + # strip out ~~~js and ~~~ at the beginning and end of the string + data.gsub!(/^~~~\s*js$|^~~~$/, '') + JSON.parse(data) + end + + # make it easier to migrate to this new sample objects syntax by figuring out the difference between the current + # json representation and a sample object one. Wrap the old json blob in something like this: + # <%= json_diff(%q{ + # ~~~ js + # ...the entire old json blob including the begining { and ending } + # ~~~ + # }, response(:user) do |h| + # ...any modifications to h you need... + # end) %> + def json_diff(old_data, new_data) + # give us an easy anchor on the page to jump to #diff + "# DIFF:\n" + json_output(diff_hash(parse_hash(old_data), parse_hash(new_data))) end def base_response(data, meta, &block) @@ -27,6 +71,9 @@ def base_response(data, meta, &block) }, &block) end + # when using these responses, make sure you always set the defining attributes in a block instead of relying on + # whatever is defined as the default. For instance, for "follow a user", make sure you set h["data"]["you_follow"] = true + # in case the default changes in the future def response(key, &block) base_response(get_hash(key), {"code"=> 200}, &block) end @@ -90,7 +137,69 @@ def paginated_response(key, &block) "url" => "https://.../", "url_expires" => "2013-01-25T03:00:00Z", "user" => "...user object...", # TODO render this as a user placholder somehow - }.freeze -end + } + + USER = { + "id" => "1", + "username" => "mthurman", + "name" => "Mark Thurman", + "description" => { + "text" => "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "html" => "Hi, I'm Mark Thurman and I'm teaching you about the @appdotnet Stream #API.", + "entities" => { + "mentions" => [{ + "name" => "appdotnet", + "id" => "3", + "pos" => 52, + "len" => 10 + }], + "hashtags" => [{ + "name" => "api", + "pos" => 70, + "len" => 4 + }], + "links" => [{ + "text" => "teaching you", + "url" => "https://github.com/appdotnet/api-spec", + "pos" => 29, + "len" => 12 + }] + } + }, + "timezone" => "US/Pacific", + "locale" => "en_US", + "avatar_image" => { + "height" => 200, + "width" => 200, + "url" => "https://example.com/avatar_image.jpg", + "is_default" => false + }, + "cover_image" => { + "width" => 320, + "height" => 118, + "url" => "https://example.com/cover_image.jpg", + "is_default" => false + }, + "type" => "human", + "created_at" => "2012-07-16T17:23:34Z", + "counts" => { + "following" => 100, + "followers" => 200, + "posts" => 24, + "stars" => 76 + }, + "follows_you" => false, + "you_blocked" => false, + "you_follow" => false, + "you_muted" => false, + "you_can_subscribe" => true, + "you_can_follow" => true, + "verified_domain" => "example.com", + "canonical_url" => "https://alpha.app.net/mthurman" + } + + USER_SELF_BLACKLIST = ['follows_you', 'you_follow', 'you_muted', 'you_blocked', 'you_can_subscribe', 'you_can_follow'] + USER_SELF = USER.reject {|key, value| USER_SELF_BLACKLIST.include?(key) } + end include Resources::Helpers From f5d5b84a697a7cfc7a6de442f940643b60cf6e31 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Tue, 9 Jul 2013 10:37:41 -0700 Subject: [PATCH 089/231] Tweak cover image dimensions --- lib/sample_objects.rb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/sample_objects.rb b/lib/sample_objects.rb index d262beb..ac16823 100644 --- a/lib/sample_objects.rb +++ b/lib/sample_objects.rb @@ -175,8 +175,8 @@ def paginated_response(key, &block) "is_default" => false }, "cover_image" => { - "width" => 320, - "height" => 118, + "width" => 960, + "height" => 264, "url" => "https://example.com/cover_image.jpg", "is_default" => false }, From 09dc211c851dac4d085f36d3169bcf9060f17d7d Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Tue, 9 Jul 2013 10:56:29 -0700 Subject: [PATCH 090/231] Adding in new integration guide page --- content/docs/authentication/flows/web.md | 21 ++------------------- layouts/default.html | 1 + 2 files changed, 3 insertions(+), 19 deletions(-) diff --git a/content/docs/authentication/flows/web.md b/content/docs/authentication/flows/web.md index 47e0aec..884f953 100644 --- a/content/docs/authentication/flows/web.md +++ b/content/docs/authentication/flows/web.md @@ -75,24 +75,7 @@ If you're building a client-side Javascript app or a mobile app that doesn't hav The access_token will be appended to the URI in the fragment section, encoded as if it were a query string. Your client-side code should parse this for the access_token. +## Finishing The Flow -## Authorize With App.net Button - -The Authorize with App.net Button is the easiest way to let people sign into and authorize your web app with their App.net credentials. If they don't have an App.net account, this button will allow new users to create an account and then authorize your app. - -### Implementation - -To implement the button on your site, you must: - -1. Replace the variables inside the brackets -1. Copy and paste the snippet below into your HTML where you want the button to show up - - -
    <a href='http://github.com/[Your%20Normal%20Authentication%20URL]' class='adn-button' data-type='authorize' data-width="145" data-height="22" data-client-id='[your client ID]' data-response-type='[token, or code]' data-scope='[scopes separated by spaces]' >Authorize with App.net</a><script>(function(d,s,id){var js,fjs=d.getElementsByTagName(s)[0];if(!d.getElementById(id)){js=d.createElement(s);js.id=id;js.src='http://d2zh9g63fcvyrq.cloudfront.net/adn.js';fjs.parentNode.insertBefore(js,fjs);}}(document, 'script', 'adn-button-js'));</script>
    - -### Best Practices - -We suggest that you put the following copy directly above or below the button: - - An App.net account is required to use [Your App Name]. You can create an account and sign in by clicking this button. +Now that you have figured out how to authenticate users we want to help you build your interface. Checkout our guide to getting started with using the Authorize with App.net button. diff --git a/layouts/default.html b/layouts/default.html index a454ba0..a9454fb 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -64,6 +64,7 @@
    • Overview
    • Web Flows
      • +
    • Web Flow Integration Guide
    • Password Flow
    • App Access Token Flow
    • Identity Delegation
      • From f05096fbfec5318982e554955a77de8b80152668 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Tue, 9 Jul 2013 11:48:52 -0700 Subject: [PATCH 091/231] Adding integration guide --- .../authentication/authorize-with-appnet.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) create mode 100644 content/docs/authentication/authorize-with-appnet.md diff --git a/content/docs/authentication/authorize-with-appnet.md b/content/docs/authentication/authorize-with-appnet.md new file mode 100644 index 0000000..e24ee00 --- /dev/null +++ b/content/docs/authentication/authorize-with-appnet.md @@ -0,0 +1,33 @@ +--- +title: "Web Flow Integration Guide" +--- + +# Web Flow Integration Guide + +Once you have decided which [web flow](/docs/authentication/flows/web/) is best for your app this guide will show you how to integrate Authorize with App.net into your web app. For your convince we have created a button that will make it easier for you. Not only will it help you create a consistent branding experience, but it will also help you sign up existing, and new users. + +* TOC +{:toc} + +## Authorize With App.net Button + +The Authorize with App.net Button is the easiest way to let people sign into and authorize your web app with their App.net credentials. If they don't have an App.net account, this button will allow new users to create an account and then authorize your app. + +### Implementation + +To implement the button on your site, you must: + +1. Build [Your authentication URL](/docs/authentication/flows/web/). +1. Replace the variables inside the brackets +1. Copy and paste the snippet below into your HTML where you want the button to show up + + +~~~html +Authorize with App.net +~~~ + +### Best Practices + +We suggest that you put the following copy directly above or below the button: + + An App.net account is required to use [Your App Name]. You can create an account and sign in by clicking this button. \ No newline at end of file From 9b619d61408b39774786f36641fe4f67a2cd3c62 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Tue, 9 Jul 2013 11:56:20 -0700 Subject: [PATCH 092/231] Adding link from web flows to integration guide --- content/docs/authentication/flows/web.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/authentication/flows/web.md b/content/docs/authentication/flows/web.md index 884f953..78fd43c 100644 --- a/content/docs/authentication/flows/web.md +++ b/content/docs/authentication/flows/web.md @@ -77,5 +77,5 @@ If you're building a client-side Javascript app or a mobile app that doesn't hav ## Finishing The Flow -Now that you have figured out how to authenticate users we want to help you build your interface. Checkout our guide to getting started with using the Authorize with App.net button. +After you have decided which flow will work for your app you should read our [Web Flow Integration Guide](/docs/authentication/authorize-with-appnet/) to help you integrate the authentication flow into your app. From 371033d4bd5e5ac35cb7d2bd222f354370b577f2 Mon Sep 17 00:00:00 2001 From: Lewis Ellis Date: Tue, 9 Jul 2013 16:13:41 -0700 Subject: [PATCH 093/231] Link to oembed metadata page in github repo --- content/docs/meta/annotations.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index 4993508..ed5585b 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -142,6 +142,7 @@ We currently define the following core annotations: | [Geolocation](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.geolocation.md) | net.app.core.geolocation | Specifies a geographic point on the Earth. | | [Language](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.language.md) | net.app.core.language | Specifies a language. | | [Embedded Media](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) | net.app.core.oembed | Provides information for displaying an image, video, or other rich content. | +| [Embedded Media Metadata](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.metadata.md) | net.app.core.oembed.metadata | Provides information for generating an oEmbed representation of a file. | We will be defining core annotations soon for the following types of data: From 828ac0867106bc070431075178035d5926ad6cf4 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Tue, 9 Jul 2013 16:19:18 -0700 Subject: [PATCH 094/231] Add in an example image --- .../docs/authentication/authorize-with-appnet.md | 4 ++++ static/images/button.png | Bin 0 -> 5946 bytes 2 files changed, 4 insertions(+) create mode 100644 static/images/button.png diff --git a/content/docs/authentication/authorize-with-appnet.md b/content/docs/authentication/authorize-with-appnet.md index e24ee00..737d36d 100644 --- a/content/docs/authentication/authorize-with-appnet.md +++ b/content/docs/authentication/authorize-with-appnet.md @@ -26,6 +26,10 @@ To implement the button on your site, you must: Authorize with App.net ~~~ +If you do everything correctly you should see a button like this: + +![example button](/assets/images/button.png) + ### Best Practices We suggest that you put the following copy directly above or below the button: diff --git a/static/images/button.png b/static/images/button.png new file mode 100644 index 0000000000000000000000000000000000000000..8ee11e55b8c9a857e71e930142f928536ef95593 GIT binary patch literal 5946 zcmZX1byO7Y^7n#tw;;82vvhYY4brvr(zzhr9g+e{qjbrlbT`u7DM$$j(n$UAd+&Si zJ?DMSd1_`ppLu5fc+O0$raBlK;}r$~0KisKl+$|N)1N0D8shUxpuOP+0ARG)%gSmh z$;tvXVXijzPEY_q5xY9WTZeGz<>1C>(MuyBqL$2wV$HN8;6NUZpDJa?9fgEn`?U#? zEiML)HHcLYNje%I08St#TFaXwP@;%=Gt^++cNGOl^QXvFDfPX=cr7e0}Pp@oOX9KP`fIhbkN^^Nx zWAo%MlhQk8`2rAGIHQ!q?!`DfIAuCYf+i0D=9PW!)S^%3L4`tTUIB-NwbV1eTe2{X zoj%%U?<-QzqFl-rzzuqc0N)^GnZtM#y8^au`ZT^vik#OkMebFS`FgJH6 zd^c#omJ=l6k|Atj)@ew>nUuC<3k45dnB-~fSE;>XQ_MO%STvAHd$e&;2svs+eBH#Z z9;8s_#4#ijoQW-Xc;_eIw%=taNo!Fz$|yXSFI;&Z5y}He=6=x77z7f5htIlp2EW0+ zS=1yfc3Rp2`0SUQ%L1BYM128wN}Xv$HZa)pBZY%`Wa-#w!nA|N6MDin0++Q3zch{ zoFq9!EK7;M0Qn+>8!lz#0r=cSm>_@_5o(8rn}H~>8LA3IVw0v?1Yk(vFQRybDQjZm zgoJN$31KXEv$)}yATD%aa{;IT=%fgsZqge7BMn-QtWFF{x%6@}f;GyLlzOu057bDh z6iu--v|_0MMXVj^>;l>{qKXKI0)_pT`}CeTEr^%0*9A0oM1GioQTQJa*?P0!G-9}3 zVeOmdLa$5_OS{-MO@ye|G4#9Y-FR0~^22MoU%-)q(39u@G<2SFsI^i#c+~V*N>Zu# zG+#(qijWWF{F04hkbENpdN#TEuwGb&y7wblT5>s!VvHK8a+eTz;LSuehcri$ z^}My{uqZdct|FU99_i!kD>2u%#DwoG`W>Mk$sYl{knRwod#BtLguo_1POA4&#tCc# z$NlwNEp87@7OO&3N&3Cn-`7qpd`L_qKwT#Tg4+{Yu3O+!YIN%`f$peH4MpH7Iyw4I zglq(FM0SL2gwiL(sgQjcEIL?BWeh`~h$Yi+5%&loB`tcglvTy4BED%9E#&e@&yN(I|id}MF7E-8pF?ZK$CSK(Iy)5X*^);;5H&;jg=!x=3fHCedf{4`=r;4pe`>IvCh@nRT8EECNq^ zOsmYZ%^c2?&n(QF737z06a{aD*lk*O@h(Cqt+*`gtVwN~mf&lr%_$Z5Gt3KRL;D}O z=N5Z?BHgQhI}_%_zEf%$GJQv00xxf8nW!7SXd!djHP3KpSg6{daQx*oE?C1)T~}b> zV`y#6XNYAu%^}M!Xw+cbkyk1SvRJ?J6+iDVTr!3l%o&Qq^}gVIS+`rWf0!SbjdIq8 zdaPtP9J;oSH}qa59V5>uXE9>s*;gsmx~slDl#X-#`|TjV-Z8&iNu!2FHpEo}!vM`TA}ka7@r zP%oJ(kn&E>jYjbbSpe1{@$suN!vqLL7S&w1m2aulAHRJAx|0i z2k)2?Lht|_5K^F+p=6_O6>8x2q8%6f%%}dvZM}ydv!=gtuynwiev{CW@F(HG%Uh1+ zW;^TJhpn)F?+j9oAww9n{Ll2;;?nm+AS({hj2N}IDq?9jk;DTP&;%y#cUSZYwSkMR ziy+~=9G-FJg#_c_z>K2|ldOBOehw&jn0X>xf80O)=R2d!Ka3n))gsQc;_U4-fvj|# zh5YZ5Ge7vI*7RxYnHhYp7qj*4>{8VPCRe!`)_U}R;4(1CM}~3?{lsG_j8v&vG`J7< zVO|k$Wxd-TUQ8c^5qaDQw^yp_I~!iIFGybR&3%|Vnp^V~@g+Ztn)j(LH^i(~Gg@g^ zcZEE*q+B8#;<^Bx6*o>-6e<&n$v0f%R%SD6GCL)LZ=yq}voL;OL?DM}Lj?7oVs5!F z2Rk?#jJ;fM^}eyR8CmP$@fHEAp9`X{u<1ShFF5jvhn^Be8X*YA~0ccjw2bq}c$#Eq|1 zk9LmQn`GQ#(&5C$S>;vLbXB0>K0UkV}XA;>uTC1n-s%j(Ic&xI$XS+5(+{o&`_pqq(i& z@u&>m!ru8CBTd)4L01n$sE5>+)FcvGK01#E+wR9FjGc|j6!fLh0nvW>a^k*Rqf|k+ z;CX5@g|mFE{0zyNp!u8C-P`ilPgCR|l6F#G79Zi;icO7v$?GQHqxbOV`rPmYiRx||%Wt`!tO*>Aw43qUG0yWG2!qagDYC3OFUGyN&v*1_@s$w)S& z_YlEI3Shp1+=ZWp{kr6n_$pzDod#fKd03=E*;wyO^%$R&b)8;!hK5?ZtfO2TI=~FI zw1jb`w4`Ic@Xc)?phaSIc1g=I(gtufXlUFYeZiLxk$iZRjCulqu`lgAI0#h%0E8TS z9Rp7THB}KSS7%NOYgbDsr;qbWo* zrz^}B#4Ri=4C3Me@$hgwTX1;zx_DanaJYET{fp%P@yJ0vtYG$Tp7yRTz`wi}macC+ z#c65(I{MG}*E^v;_W$+d;_>gWo&yB^)quD;xj_Hneuj$um5ONE`#_xxcH#VcID@KKLbN^E6G99+wbPITBq{PIO*O3)jSy|cHmAx(XvhwtMxe6f@dv~|DpbwH8@A%Pr5blA_ zrm7uCo0OtnZDsI%>~$#-9JIwd6lARnPTCOJo8p<5eR3l3rwD%BX`9^%3bIr4p6;Z5 zJmw-(B|4bmA8|P;2xM&~8<`9LE_L&L|4a&_ZXr+b`z4_03|l(~FNpd?dVE*CapgZg2WD z#?lg$I9-~c7Owa@Vo9{bPxl--F8~HTCU#!7bAe~VdS^6_zkdCiWN#nj_RCT}X!x^k zL*kR$5P5-OC`s?YW zySeDd+0|3l3BkW@cSGYro~KXy9Yc7l2%8h#jO6{I%l_>6`kfY4hSLw8VlSzdP%=Eq zH*!ZmqlzBybq0hF=)E2f#eb_&nwUkOh~QVW{yb?oulR%x;6gCa8X?%*OvWK2P(Rc{ zur^+}{A^!-u%)fYfv1UFq7z#7megUrQZ?;JEpWU7$` ztyr0SBf+BDH)C_f*qBZM+go%?gN?6)92W$>>QrN4$81LSGeFd_?Au8Kt~gOXG)-b- z-+gA-Ky8V6clSl$QHklN{Wp;P)C|R7<$|zC@DmCepIP7&#J(7rx@hLp8w8doro!Z2}}wf2c>y z7rAhcyqq}O+r;6kvCtRSELjQy>*JWj&{rX`K83X1xF_h6BinT~CykyhA{4|ft8FNf zzyb`_at%2s_t#6>R#+Pfh^Z6a53yT$K2?G^&=_Cd9AA_emyFcRh;m}+^33$pEBdB^eC3HDh(smF5@HLZ-i3JsLQOZ_KJ!L1Xxlnp3>oZEVcnEzB}>JW@yT_sM(q;epv?5N|>EVz%sSMWoXJSub31?X`x4#gaEtE3N-;_Jrn5X}+cMNUKaGq$6<^RqqJn4G7VYkJ9Mib%LOn#hbX zZj|Lbrei9xGo}qAu7i!O4-Wy}H^-ijK#n7a_sP>tPRDo!oTk#F!G9R1;m#_!TaD)y zT|*fM=c+#58X5edWx~II81g?5ix3r+m&(poj))V%ej7>=d8EP#hcA3l?w3)*`$ssc zNAot~IPE{G4A9Nne0eA-*Iy)iyAy9aYCL6{r8W8GY=V~o9U)o!M^s&F&IM8d|U^HVyj4f)+DfbULj_*0%8u%pM@f z)*bxn`%nt|Atie$zh<$60hns?y$B%U_Zdjj=>~()8AHvvJfp08ix(TiLE1oBQ+Gl8 z2Z{^AIy1)|f22e6AHqO8hI~b$jVn8@(aGINRjIiHhZO6ljL6tyM0_g+>hj^j`hQXs2!D?l<=VRkN4hL`rhDT zR+)g4qP|#tD#}W|M}LEx#8FzfI3L`|!w+F49%0xdG4?&}>Om^*egP#m(29DI*M#2o z$aR`=r!~wwcfSy+5JEUK;pt5!x@#_+`3)>CsN!C)1BYn$|)Af z=@!s9yDY+k3^s=hfR(NLW!T{M)Ed)+RC0_TB znfoK)u?$X76P9L#e}j<=BrvdDC!2oV7HKmF6^zWQt=;_XdmeM&NuY@G)#W@s>0)q4 zJ^GjL%nBiWu0-LIh>&+T2~v3ADWup9W|Uy07RKM?p}@pX=medwu^!PppQ}7XX$pBl h`k+G6d;I-BPlK Date: Wed, 10 Jul 2013 12:52:36 -0700 Subject: [PATCH 095/231] Adding in copy changes for auth with app.net buttons --- content/docs/authentication/authorize-with-appnet.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/content/docs/authentication/authorize-with-appnet.md b/content/docs/authentication/authorize-with-appnet.md index 737d36d..bbf53a2 100644 --- a/content/docs/authentication/authorize-with-appnet.md +++ b/content/docs/authentication/authorize-with-appnet.md @@ -4,14 +4,22 @@ title: "Web Flow Integration Guide" # Web Flow Integration Guide -Once you have decided which [web flow](/docs/authentication/flows/web/) is best for your app this guide will show you how to integrate Authorize with App.net into your web app. For your convince we have created a button that will make it easier for you. Not only will it help you create a consistent branding experience, but it will also help you sign up existing, and new users. +Now that you've identified which [web flow](/docs/authentication/flows/web/) to use with your app, it's time to expose this to end users. * TOC {:toc} ## Authorize With App.net Button -The Authorize with App.net Button is the easiest way to let people sign into and authorize your web app with their App.net credentials. If they don't have an App.net account, this button will allow new users to create an account and then authorize your app. +The easiest way to integrate a web flow into your app is through an "Authorize with App.net" Button, which allows current App.net users to enjoy the ease of authorizing your app in two clicks. Less means more, as they'll be able to start using your app even faster. + +As an added benefit, this button will also allow new users to sign up for a free account and then authorize your app. + +Why you should implement this button: + +1. It's easy: Add this button to your site in seconds. +1. It's beautiful: it looks good and potential users will recognize the App.net branding. +1. It's useful: One button helps your get new and existing accounts using your app. ### Implementation From c9c18445f1605ba365c12f0e7e4423ef1ffcc03c Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 10 Jul 2013 12:53:47 -0700 Subject: [PATCH 096/231] Forgot on copy change --- content/docs/authentication/authorize-with-appnet.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/authentication/authorize-with-appnet.md b/content/docs/authentication/authorize-with-appnet.md index bbf53a2..35ef371 100644 --- a/content/docs/authentication/authorize-with-appnet.md +++ b/content/docs/authentication/authorize-with-appnet.md @@ -19,7 +19,7 @@ Why you should implement this button: 1. It's easy: Add this button to your site in seconds. 1. It's beautiful: it looks good and potential users will recognize the App.net branding. -1. It's useful: One button helps your get new and existing accounts using your app. +1. It's useful: One button helps your app get new and existing App.net users. ### Implementation From bcddb5960dd23cff15c7164a147b52c2f4d46dac Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 10 Jul 2013 17:06:17 -0700 Subject: [PATCH 097/231] Adding more to the web flow integration guide --- content/docs/authentication/authorize-with-appnet.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/docs/authentication/authorize-with-appnet.md b/content/docs/authentication/authorize-with-appnet.md index 35ef371..dc8f119 100644 --- a/content/docs/authentication/authorize-with-appnet.md +++ b/content/docs/authentication/authorize-with-appnet.md @@ -15,11 +15,11 @@ The easiest way to integrate a web flow into your app is through an "Authorize w As an added benefit, this button will also allow new users to sign up for a free account and then authorize your app. -Why you should implement this button: +### Benefits -1. It's easy: Add this button to your site in seconds. -1. It's beautiful: it looks good and potential users will recognize the App.net branding. -1. It's useful: One button helps your app get new and existing App.net users. +1. **It's easy**: Add this button to your site in seconds. +1. **It's beautiful**: it looks good and potential users will recognize the App.net branding. +1. **It's useful**: One button helps your app get new and existing App.net users. ### Implementation From b11de05730cb1dd5e2ec3bae01ffb51ed6fcdcfa Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 10 Jul 2013 17:32:39 -0700 Subject: [PATCH 098/231] Updating the copy for the authorize button --- content/docs/authentication/authorize-with-appnet.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/authentication/authorize-with-appnet.md b/content/docs/authentication/authorize-with-appnet.md index dc8f119..8208b14 100644 --- a/content/docs/authentication/authorize-with-appnet.md +++ b/content/docs/authentication/authorize-with-appnet.md @@ -17,9 +17,9 @@ As an added benefit, this button will also allow new users to sign up for a free ### Benefits -1. **It's easy**: Add this button to your site in seconds. -1. **It's beautiful**: it looks good and potential users will recognize the App.net branding. -1. **It's useful**: One button helps your app get new and existing App.net users. +1. **It's easy**: Add an Authorize with App.net button to your site in seconds. +1. **It's beautiful**: The minimal style of the button is versatile and users will recognize the App.net branding. +1. **It's useful**: Your potential users can either sign up or sign in to your app with the same button. ### Implementation From 8902840c99103098462f0be19827386caf7be991 Mon Sep 17 00:00:00 2001 From: Lewis Ellis Date: Wed, 10 Jul 2013 18:04:38 -0700 Subject: [PATCH 099/231] Fixed name of oEmbed Metadata --- content/docs/meta/annotations.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index ed5585b..9a85679 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -142,7 +142,7 @@ We currently define the following core annotations: | [Geolocation](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.geolocation.md) | net.app.core.geolocation | Specifies a geographic point on the Earth. | | [Language](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.language.md) | net.app.core.language | Specifies a language. | | [Embedded Media](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) | net.app.core.oembed | Provides information for displaying an image, video, or other rich content. | -| [Embedded Media Metadata](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.metadata.md) | net.app.core.oembed.metadata | Provides information for generating an oEmbed representation of a file. | +| [oEmbed Metadata](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.metadata.md) | net.app.core.oembed.metadata | Provides information for generating an oEmbed representation of a file. | We will be defining core annotations soon for the following types of data: From 5edc1f6ba5655cb24b90e2f9ffaeaa73457e31e0 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 17 Jul 2013 14:01:20 -0700 Subject: [PATCH 100/231] Relax restrictions on user provided link text --- content/docs/meta/entities.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index b1007d2..6061413 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -198,7 +198,9 @@ Entities are automatically extracted from the post text but there are 2 cases wh ### Links with custom anchor text -If you'd like to provide a link without including the entire URL in your post text or user description, you can specify a custom link at Post creation time or User update time. **If you include a list of links in your Post — even an empty list — App.net by default will not extract any links on the server.** Mentions and hashtags will still be extracted and your provided links must not overlap with these extracted entities. So you **cannot** have a custom link around a hashtag or mention. If you want App.net to still extract links, you can pass the `parse_links: true` option to App.net. User provided links will take precedence over any links App.net detects. For example, the following JSON will create a post to 2 links 1) the parsed link to App.net and 2) the user provided link to the App.net blog: +If you'd like to provide a link without including the entire URL in your post text or user description, you can specify a custom link at Post creation time or User update time. **If you include a list of links in your Post — even an empty list — App.net by default will not extract any links on the server.** Mentions and hashtags will still be extracted. If you want App.net to still extract links, you can pass the `parse_links: true` option to App.net. User provided links will take precedence over any links, mentions, or hashtags that App.net detects. However, a user provided link can not partially overlap with a mention or hashtag. + +As an example, the following JSON will create a post to 2 links 1) the parsed link to App.net and 2) the user provided link to the App.net blog: ~~~js { From b87a9bcf7ddea1a2ac7b288857a9a8424901a294 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 17 Jul 2013 17:08:04 -0700 Subject: [PATCH 101/231] Add is_leading property to mentions --- content/docs/meta/entities.md | 6 ++++++ content/docs/resources/post/index.md | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index 6061413..ad50569 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -28,6 +28,7 @@ Bring another user's attention to your post. A mention starts with @@      integer The length of the substring in text that represents this mention. Since @ is included, len will be the length of the name + 1. + + is_leading + boolean + Is this mention a leading mention? A leading mention is a mention at the beginning of a post's text. This is used when computing the whether the post is a directed post. + ## Hashtags diff --git a/content/docs/resources/post/index.md b/content/docs/resources/post/index.md index 8580f3f..52001e6 100644 --- a/content/docs/resources/post/index.md +++ b/content/docs/resources/post/index.md @@ -250,7 +250,7 @@ Where noted, Post endpoints respond to the following query string parameters: include_directed_posts Optional integer (0 or 1) - Should Posts directed at people I don't follow be included? A directed Post is a Post that starts with 1 or more @mentions. A machine only Post with mentions is also considered a directed Post. Defaults to false for "My Stream" and true everywhere else. + Should Posts directed at people I don't follow be included? A directed Post is a Post that has leading mentions (mentions at the beginning of the text). A machine only Post with mentions is also considered a directed Post. Defaults to false for "My Stream" and true everywhere else. include_machine From 36c67849d34ad0bd5e32cff1fbeb0051098aff02 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 17 Jul 2013 17:13:10 -0700 Subject: [PATCH 102/231] Link back to leading mentions section --- content/docs/resources/post/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/post/index.md b/content/docs/resources/post/index.md index 52001e6..c806908 100644 --- a/content/docs/resources/post/index.md +++ b/content/docs/resources/post/index.md @@ -250,7 +250,7 @@ Where noted, Post endpoints respond to the following query string parameters: include_directed_posts Optional integer (0 or 1) - Should Posts directed at people I don't follow be included? A directed Post is a Post that has leading mentions (mentions at the beginning of the text). A machine only Post with mentions is also considered a directed Post. Defaults to false for "My Stream" and true everywhere else. + Should Posts directed at people I don't follow be included? A directed Post is a Post that has leading mentions (mentions at the beginning of the text). A machine only Post with mentions is also considered a directed Post. Defaults to false for "My Stream" and true everywhere else. include_machine From 5d48ee8d814d41e5a03c8072eb145b09b45ed59a Mon Sep 17 00:00:00 2001 From: Derek Shockey Date: Fri, 19 Jul 2013 14:24:04 -0700 Subject: [PATCH 103/231] Per the Pagination docs, min_id and max_id are strings --- content/docs/basics/responses.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/basics/responses.md b/content/docs/basics/responses.md index f5af812..919d9e9 100644 --- a/content/docs/basics/responses.md +++ b/content/docs/basics/responses.md @@ -34,8 +34,8 @@ The second key present, ```meta```, corresponds to an object containing addition "updated_at": "2012-11-09T23:35:38Z", "version": "NWoZK3kTsExUV00Ywo1G5jlUKKs" }, - "max_id": 65039, - "min_id": 65039, + "max_id": "65039", + "min_id": "65039", "more": true } } From 5b5030ef0367f8883041ffb8ddca847afc15316b Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Wed, 24 Jul 2013 17:02:14 -0700 Subject: [PATCH 104/231] Update doc gems & add post search --- .ackrc | 3 + Gemfile | 10 ++- Guardfile | 8 ++ content/docs/resources/place/index.md | 20 ++--- content/docs/resources/post/search.md | 123 ++++++++++++++++++++++++++ layouts/default.html | 3 +- layouts/partials/endpoints/post.md | 6 ++ layouts/partials/parameters-typed.md | 10 ++- lib/helpers.rb | 17 ++-- 9 files changed, 175 insertions(+), 25 deletions(-) create mode 100644 .ackrc create mode 100644 Guardfile create mode 100644 content/docs/resources/post/search.md diff --git a/.ackrc b/.ackrc new file mode 100644 index 0000000..1533adc --- /dev/null +++ b/.ackrc @@ -0,0 +1,3 @@ +--ignore-dir=.git +--ignore-dir=tmp +--ignore-dir=output diff --git a/Gemfile b/Gemfile index 102919f..44d5760 100644 --- a/Gemfile +++ b/Gemfile @@ -1,15 +1,17 @@ source "https://rubygems.org/" -gem 'nanoc', '3.6.2' +gem 'nanoc', '3.6.4' gem 'adsf', '1.1.1' gem 'fssm', '0.2.10' -gem 'kramdown', '1.0.1' +gem 'kramdown', '1.1.0' gem 'coderay', '1.0.9' -gem 'pygments.rb', '0.4.2' +gem 'pygments.rb', '0.5.2' gem 'nokogiri', '1.5.9' gem 'rack', '1.5.2' gem 'colored', '1.2' gem 'cri', '2.3.0' gem 'posix-spawn', '0.3.6' gem 'yajl-ruby', '1.1.0' - +gem 'listen', '1.2.2' +gem 'guard-nanoc', '1.0.1' +gem 'rb-readline' diff --git a/Guardfile b/Guardfile new file mode 100644 index 0000000..1279cd9 --- /dev/null +++ b/Guardfile @@ -0,0 +1,8 @@ +# A sample Guardfile +# More info at https://github.com/guard/guard#readme + +guard 'nanoc' do + watch('nanoc.yaml') # Change this to config.yaml if you use the old config file name + watch('Rules') + watch(%r{^(content|layouts|lib)/.*$}) +end diff --git a/content/docs/resources/place/index.md b/content/docs/resources/place/index.md index 887336d..a2a4164 100644 --- a/content/docs/resources/place/index.md +++ b/content/docs/resources/place/index.md @@ -228,25 +228,25 @@ Returns a list of Places sorted by distance or distance/string match if `q` is p <%= endpoint "GET", "places/search", "User" %> -<%= query_params_typed [ +<%= query_params_typed 'Query String Parameters', [ - ["latitude", "decimal", "Latitude of search location. Combined with longitude to create central point of search results."], + ["latitude", :required, "decimal", "Latitude of search location. Combined with longitude to create central point of search results."], - ["longitude", "decimal", "Longitude of search location. Combined with latitude to create central point of search results."], + ["longitude", :required, "decimal", "Longitude of search location. Combined with latitude to create central point of search results."], - ["q", "string", "(Optional) The name-based search query. Can be a partial string — for example, 'cre' will find any local 'creameries' and 'ice cream' locations."], + ["q", :optional, "string", "The name-based search query. Can be a partial string — for example, 'cre' will find any local 'creameries' and 'ice cream' locations."], - ["radius", "decimal", "(Optional) Approximate radius (in meters) of bounding circle on results. For example, supplying radius=100 will limit all locations to be within 100 meters. Defaults to 100, ranges between 0.001 and 50,000."], + ["radius", :optional, "decimal", "Approximate radius (in meters) of bounding circle on results. For example, supplying radius=100 will limit all locations to be within 100 meters. Defaults to 100, ranges between 0.001 and 50,000."], - ["count", "int", "(Optional) Number of results to return. Defaults to 20, ranges between 1 and 100."], + ["count", :optional, "integer", "Number of results to return. Defaults to 20, ranges between 1 and 100."], - ["remove_closed", "int (0 or 1)", "(Optional) Set to 0 if you would like the result to include entities which are closed (is_closed=1) or 1 if you would only prefer to see results for entities that are open. Defaults to 1."], + ["remove_closed", :optional, "int (0 or 1)", "Set to 0 if you would like the result to include entities which are closed (is_closed=1) or 1 if you would only prefer to see results for entities that are open. Defaults to 1."], - ["altitude", "decimal", "(Optional) Altitude of search location (in meters). Not presently used to generate search results but may be later."], + ["altitude", :optional, "decimal", "Altitude of search location (in meters). Not presently used to generate search results but may be later."], - ["horizontal_accuracy", "decimal", "(Optional) Accuracy of latitude/longitude parameters (in meters). Not presently used to generate search results but may be later."], + ["horizontal_accuracy", :optional, "decimal", "Accuracy of latitude/longitude parameters (in meters). Not presently used to generate search results but may be later."], - ["vertical_accuracy", "decimal", "(Optional) Accuracy of altitude parameter (in meters). Not presently used to generate search results but may be later."] + ["vertical_accuracy", :optional, "decimal", "Accuracy of altitude parameter (in meters). Not presently used to generate search results but may be later."] ]%> diff --git a/content/docs/resources/post/search.md b/content/docs/resources/post/search.md new file mode 100644 index 0000000..feef4b5 --- /dev/null +++ b/content/docs/resources/post/search.md @@ -0,0 +1,123 @@ +--- +title: "Post Search" +--- + +# Search + +* TOC +{:toc} + +## Search for Posts + +Returns [Post](/docs/resources/post/) objects which match a given search query. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string. + +<%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. + +<%= endpoint "GET", "posts/search", "None" %> + +<%= query_params_typed 'General Parameters', [ + + ["index", :optional, "string", "Type of index to use. The default (and currently, the only) index is complete, which searches all posts. We may add additional index types later (e.g., an index only of recent posts, for speed.)"], + + ["order", :optional, "string", "One of: id, score. Searches of ordering id are returned in roughly the same order as other streams, and support pagination. Searches of ordering score are returned by a relevance score. Currently, the only ordering that supports pagination is id, and we are working on improving relevance scores."], + +]%> + +<%= query_params_typed 'Search Query Parameters', [ + + ["query", :optional, "string", "Automatically attempts to extract hashtags and mentions while searching text. If you do not want this behavior, you can use more specific parameters below."], + + ["text", :optional, "string", "Include posts containing certain text."], + ["hashtags", :optional, "string", "Include posts tagged with certain hashtags"], + ["links", :optional, "string", "Include posts linking to certain URLs"], + ["link_domains", :optional, "string", "Include posts linking to certain domains. Do not include \"www.\""], + ["mentions", :optional, "string", "Include posts mentioning certain users, by username. Do not include @"], + ["leading_mentions", :optional, "string", "Include posts directed at users, by username. Do not include @"], + +]%> + +<%= query_params_typed 'Filter Parameters', [ + ["annotation_types", :optional, "string", "Only include posts with a specific annotation type, e.g., net.app.core.fallback_url"], + ["attachment_types", :optional, "string", "Only include posts with a specific file type attached via the net.app.core.file_list annotation"], + ["crosspost_url", :optional, "string", "Only include posts which are crossposts of a specific URL, via the net.app.core.crosspost annotation"], + ["crosspost_domain", :optional, "string", "Similar to crosspost_url, but only match on the host portion of the URL. Do not include \"www.\""], + ["place_id", :optional, "string", "Only include posts which are check-ins at a specific place, via the net.app.core.checkin annotation"], + + ["is_reply", :optional, "int (0 or 1)", "Only include replies"], + ["is_directed", :optional, "int (0 or 1)", "Only include posts with leading mentions, i.e., posts which were directed at other users"], + ["has_location", :optional, "int (0 or 1)", "Only include posts containing geo coordinates, i.e., tagged with the net.app.core.location annotation"], + ["has_checkin", :optional, "int (0 or 1)", "Only include posts containing place IDs, i.e., tagged with the net.app.core.checkin annotation"], + ["is_crosspost", :optional, "int (0 or 1)", "Only include posts which are crossposts, i.e., tagged with the net.app.core.crosspost annotation"], + ["has_attachment", :optional, "int (0 or 1)", "Only include posts with file attachments"], + ["has_oembed_photo", :optional, "int (0 or 1)", "Only include posts with photo oembed annotations"], + ["has_oembed_video", :optional, "int (0 or 1)", "Only include posts with video (not html5video) oembed annotations"], + ["has_oembed_html5video", :optional, "int (0 or 1)", "Only include posts with html5video oembed annotations"], + ["has_oembed_rich", :optional, "int (0 or 1)", "Only include posts with rich oembed anntations"], + + ["language", :optional, "string", "Only include posts with a certain language tagged with the net.app.core.language annotation."], + ["client_id", :optional, "string", "Only include posts created by a certain app. Use the alphanumeric client_id"], + ["creator_id", :optional, "string", "Only include posts created by a specific user. Use the user ID, not the username"], + ["reply_to", :optional, "string", "Only include immediate replies to a given post ID"], + ["thread_id", :optional, "string", "Only include posts on a specific thread"], + +]%> + +#### Example + +> GET https://alpha-api.app.net/stream/0/posts/search?hashtags=newsocialnetwork&mentions=berg&is_directed=1&count=-1 + +~~~ js +{ + "data": [ + ... + { + "id": "1", // note this is a string + "user": { + ... + }, + "created_at": "2012-07-16T17:25:47Z", + "text": "@berg FIRST post on this new site #newsocialnetwork", + "html": "@berg FIRST post on this new site #newsocialnetwork.", + "source": { + "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4", + "name": "Clientastic for iOS", + "link": "http://app.net/" + }, + "machine_only": false, + "reply_to": null, + "thread_id": "1", + "num_replies": 3, + "num_reposts": 0, + "num_stars": 0, + "entities": { + "mentions": [{ + "name": "berg", + "id": "2", + "pos": 0, + "len": 5 + }], + "hashtags": [{ + "name": "newsocialnetwork", + "pos": 34, + "len": 17 + }], + "links": [{ + "text": "this new site", + "url": "https://join.app.net/" + "pos": 20, + "len": 13 + }] + }, + "you_reposted": false, + "you_starred": false + }, + ], + "meta": { + "code": 200, + "max_id": "33", + "min_id": "1", + "more": true + } +} +~~~ + diff --git a/layouts/default.html b/layouts/default.html index a9454fb..e5fd1dc 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -5,7 +5,7 @@ <%= @item[:title] %> - App.net API Documentation - + @@ -91,6 +91,7 @@
    • Reposts
    • Stars
    • Report
      • +
    • Search
  • Channel
      • diff --git a/layouts/partials/endpoints/post.md b/layouts/partials/endpoints/post.md index cb7fc14..dc23f9e 100644 --- a/layouts/partials/endpoints/post.md +++ b/layouts/partials/endpoints/post.md @@ -110,5 +110,11 @@ /stream/0/posts/{post_id}/report User + + Search for Posts + GET + /stream/0/posts/search + None + diff --git a/layouts/partials/parameters-typed.md b/layouts/partials/parameters-typed.md index 6402c42..4606e45 100644 --- a/layouts/partials/parameters-typed.md +++ b/layouts/partials/parameters-typed.md @@ -1,10 +1,11 @@ #### <%= header %> - +
      - + + @@ -12,9 +13,10 @@ <% params.each do |param| %> - + + <% end %> -
      NameTypeRequired?Type Description
      <%= param[0] %><%= param[1] %><%= param[1].to_s.capitalize %> <%= param[2] %><%= param[3] %>
      \ No newline at end of file + diff --git a/lib/helpers.rb b/lib/helpers.rb index 73c7c0c..7e19dc5 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -30,8 +30,8 @@ def query_params(params = []) render '/partials/parameters', :header => "Query String Parameters", :params => params end -def query_params_typed(params = []) - render "/partials/parameters-typed", :header => "Query String Parameters", :params => params +def query_params_typed(header = "Query String Parameters", params = []) + render "/partials/parameters-typed", :header => header, :params => params end def post_params(params = []) @@ -47,9 +47,14 @@ def pagination_note() end def general_params_note_for(type) - 'This endpoint responds to general '+type.capitalize+' parameters.' + 'This endpoint responds to general '+type.capitalize+' parameters.' end -def env_var(name) - ENV[name] -end \ No newline at end of file +# feel free to override these from your environment +def lanai_hostname() + ENV['LANAI_HOSTNAME'] || 'app.net' +end + +def local_hostname() + ENV['LOCAL_HOSTNAME'] || 'localhost' +end From 07da88b9ae231388d104bca65b89dad19bc16cd1 Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Wed, 24 Jul 2013 17:06:58 -0700 Subject: [PATCH 105/231] add search API to intro --- content/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/index.md b/content/index.md index 8fba412..c7224f2 100644 --- a/content/index.md +++ b/content/index.md @@ -16,6 +16,7 @@ To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adna {::options parse_block_html="true" /}
      +* (7/25/2013) **Introducing the Search API** — check out the documentation for [Post Search](/docs/resources/post/search/). * (6/17/2013) **Introducing the User Stream API** — check out the documentation for [User Streams](/docs/resources/user-stream/). * (2/5/2013) **Introducing the Place API** — check out the documentation for [Places](/docs/resources/place/). * (1/28/2013) **Introducing the File API** — check out the documentation for [Files](/docs/resources/file/). From 71d857371dcf373696b36aaa9396bfa9c12cc45a Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Wed, 24 Jul 2013 17:37:22 -0700 Subject: [PATCH 106/231] search DOES currently require a token --- content/docs/resources/post/search.md | 4 ++-- layouts/partials/endpoints/post.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/resources/post/search.md b/content/docs/resources/post/search.md index feef4b5..feb3615 100644 --- a/content/docs/resources/post/search.md +++ b/content/docs/resources/post/search.md @@ -13,13 +13,13 @@ Returns [Post](/docs/resources/post/) objects which match a given search query. <%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. -<%= endpoint "GET", "posts/search", "None" %> +<%= endpoint "GET", "posts/search", "Any" %> <%= query_params_typed 'General Parameters', [ ["index", :optional, "string", "Type of index to use. The default (and currently, the only) index is complete, which searches all posts. We may add additional index types later (e.g., an index only of recent posts, for speed.)"], - ["order", :optional, "string", "One of: id, score. Searches of ordering id are returned in roughly the same order as other streams, and support pagination. Searches of ordering score are returned by a relevance score. Currently, the only ordering that supports pagination is id, and we are working on improving relevance scores."], + ["order", :optional, "string", "One of: id (default), score. Searches of ordering id are returned in roughly the same order as other streams, and support pagination. Searches of ordering score are returned by a relevance score. Currently, the only ordering that supports pagination is id, and we are working on improving relevance scores."], ]%> diff --git a/layouts/partials/endpoints/post.md b/layouts/partials/endpoints/post.md index dc23f9e..b611af5 100644 --- a/layouts/partials/endpoints/post.md +++ b/layouts/partials/endpoints/post.md @@ -114,7 +114,7 @@ Search for Posts GET /stream/0/posts/search - None + Any From ab855a8571e56c1155d21adeb1159797bb4d056a Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Wed, 24 Jul 2013 18:51:30 -0700 Subject: [PATCH 107/231] duerig nits --- content/docs/resources/post/search.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/resources/post/search.md b/content/docs/resources/post/search.md index feb3615..808f632 100644 --- a/content/docs/resources/post/search.md +++ b/content/docs/resources/post/search.md @@ -11,7 +11,7 @@ title: "Post Search" Returns [Post](/docs/resources/post/) objects which match a given search query. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string. -<%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. +<%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. Separate lists of terms by spaces. <%= endpoint "GET", "posts/search", "Any" %> @@ -28,7 +28,7 @@ Returns [Post](/docs/resources/post/) objects which match a given search query. ["query", :optional, "string", "Automatically attempts to extract hashtags and mentions while searching text. If you do not want this behavior, you can use more specific parameters below."], ["text", :optional, "string", "Include posts containing certain text."], - ["hashtags", :optional, "string", "Include posts tagged with certain hashtags"], + ["hashtags", :optional, "string", "Include posts tagged with certain hashtags. Do not include #"], ["links", :optional, "string", "Include posts linking to certain URLs"], ["link_domains", :optional, "string", "Include posts linking to certain domains. Do not include \"www.\""], ["mentions", :optional, "string", "Include posts mentioning certain users, by username. Do not include @"], From 553a31b3816385fe3ebb54a4a4e951d642842d6a Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Thu, 25 Jul 2013 12:42:19 -0700 Subject: [PATCH 108/231] update docs to describe new behavior --- content/docs/resources/post/search.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/docs/resources/post/search.md b/content/docs/resources/post/search.md index 808f632..2209676 100644 --- a/content/docs/resources/post/search.md +++ b/content/docs/resources/post/search.md @@ -9,7 +9,7 @@ title: "Post Search" ## Search for Posts -Returns [Post](/docs/resources/post/) objects which match a given search query. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string. +Returns [Post](/docs/resources/post/) objects which match a given search query. Searches ordered by `id` require at least one query or filter to be specified; searches ordered by `score` require at least one query and zero or more filters to be specified. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string. <%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. Separate lists of terms by spaces. @@ -26,17 +26,17 @@ Returns [Post](/docs/resources/post/) objects which match a given search query. <%= query_params_typed 'Search Query Parameters', [ ["query", :optional, "string", "Automatically attempts to extract hashtags and mentions while searching text. If you do not want this behavior, you can use more specific parameters below."], - ["text", :optional, "string", "Include posts containing certain text."], - ["hashtags", :optional, "string", "Include posts tagged with certain hashtags. Do not include #"], - ["links", :optional, "string", "Include posts linking to certain URLs"], - ["link_domains", :optional, "string", "Include posts linking to certain domains. Do not include \"www.\""], - ["mentions", :optional, "string", "Include posts mentioning certain users, by username. Do not include @"], - ["leading_mentions", :optional, "string", "Include posts directed at users, by username. Do not include @"], + ]%> <%= query_params_typed 'Filter Parameters', [ + ["hashtags", :optional, "string", "Only include posts tagged with certain hashtags. Do not include #"], + ["links", :optional, "string", "Only include posts linking to certain URLs"], + ["link_domains", :optional, "string", "Only include posts linking to certain domains. Do not include \"www.\""], + ["mentions", :optional, "string", "Only include posts mentioning certain users, by username. Do not include @"], + ["leading_mentions", :optional, "string", "Only include posts directed at users, by username. Do not include @"], ["annotation_types", :optional, "string", "Only include posts with a specific annotation type, e.g., net.app.core.fallback_url"], ["attachment_types", :optional, "string", "Only include posts with a specific file type attached via the net.app.core.file_list annotation"], ["crosspost_url", :optional, "string", "Only include posts which are crossposts of a specific URL, via the net.app.core.crosspost annotation"], From 23320af6c8f1245b32afb16f4e20272ca1593cb9 Mon Sep 17 00:00:00 2001 From: Lewis Ellis Date: Mon, 5 Aug 2013 16:23:05 -0700 Subject: [PATCH 109/231] Added links to user/channel replacement annotations --- content/docs/meta/annotations.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index 9a85679..eb7b7b5 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -185,10 +185,12 @@ As explained in the [schema for the `net.app.core.file` value](https://github.co } ~~~ -We currently define the follow replacement values in annotations: +We currently define the following replacement values in annotations: | Name | Key | Description | | ---- | --- | ----------- | | [File](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file.md) | +net.app.core.file | Add information about an App.net [File](/docs/resources/file/) to an annotation. | | [File List](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file_list.md) | +net.app.core.file_list | Add information about a list of App.net [Files](/docs/resources/file/) to an annotation. | | [Place](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.place.md) | +net.app.core.place | Add information about a [Place](/docs/resources/place/) to an annotation. | +| [User](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.user.md) | +net.app.core.user | Add information about a [User](/docs/resources/user/) to an annotation. | +| [Channel](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.channel.md) | +net.app.core.channel | Add information about a [Channel](/docs/resources/channel/) to an annotation. | \ No newline at end of file From a22525cd91acb8e789311a229db14f5fafe6bd8e Mon Sep 17 00:00:00 2001 From: Lewis Ellis Date: Thu, 8 Aug 2013 16:42:15 -0700 Subject: [PATCH 110/231] Link to phototag annotation --- content/docs/meta/annotations.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index eb7b7b5..d9df7db 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -133,6 +133,7 @@ We currently define the following core annotations: | [Attachments](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.attachments.md) | net.app.core.attachments | A pointer to App.net [Files](/docs/resources/file/) that are attached to the object being annotated. | | [Channel Invite](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.channel.invite.md) | net.app.core.channel.invite | A pointer to a [Channel](/docs/resources/channel/). | | [Checkin](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.checkin.md) | net.app.core.checkin | Indicates a user has "checked in" to a [Place](/docs/resources/place/). | +| [Phototag](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.phototag.md) | net.app.core.phototag | Indicates a user appears in a photo | | [Crosspost](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.crosspost.md) | net.app.core.crosspost | Specifies the original or canonical source of a Post on App.net from somewhere else on the web. | | [Blog URL](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.directory.blog.md) | net.app.core.directory.blog | A pointer to a user's blog. | | [Facebook ID](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.directory.facebook.md) | net.app.core.directory.facebook | A pointer to a user's Facebook account. | From 8800b8f15bafe5043ea3825e6d9c9cdc45d0fc5c Mon Sep 17 00:00:00 2001 From: Lewis Ellis Date: Fri, 9 Aug 2013 10:48:32 -0700 Subject: [PATCH 111/231] Pulling channel replacement for now --- content/docs/meta/annotations.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index d9df7db..7f3cf17 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -194,4 +194,3 @@ We currently define the following replacement values in annotations: | [File List](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file_list.md) | +net.app.core.file_list | Add information about a list of App.net [Files](/docs/resources/file/) to an annotation. | | [Place](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.place.md) | +net.app.core.place | Add information about a [Place](/docs/resources/place/) to an annotation. | | [User](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.user.md) | +net.app.core.user | Add information about a [User](/docs/resources/user/) to an annotation. | -| [Channel](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.channel.md) | +net.app.core.channel | Add information about a [Channel](/docs/resources/channel/) to an annotation. | \ No newline at end of file From a7498467039deebdc992c65f645b25a2de37333e Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 12 Aug 2013 18:19:58 -0700 Subject: [PATCH 112/231] Add config endpoint --- content/docs/resources/config/index.md | 129 +++++++++++++++++++++++++ content/docs/resources/index.md | 4 + layouts/default.html | 1 + layouts/partials/endpoints/config.md | 18 ++++ lib/sample_objects.rb | 27 ++++++ 5 files changed, 179 insertions(+) create mode 100644 content/docs/resources/config/index.md create mode 100644 layouts/partials/endpoints/config.md diff --git a/content/docs/resources/config/index.md b/content/docs/resources/config/index.md new file mode 100644 index 0000000..edd4ed3 --- /dev/null +++ b/content/docs/resources/config/index.md @@ -0,0 +1,129 @@ +--- +title: "Configuration" +--- + +# Configuration + +* TOC +{:toc} + +The Configuration object defines platform-wide variables that Apps can use to make sure their behavior is consistent with the platform. + +## Example Configuration object + +<%= json(:config) %> + +## Configuration fields + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
      FieldTypeDescription
      textobject + Configuration that is common to all text fields (post.text, message.text, user.description.text). +
      + + + + + + + + + + + +
      FieldTypeDescription
      uri_template_lengthobjectA mapping from each of the possible URI template replacement values to the number of characters that are "used" upon replacement.
      +
      userResource Configuration ObjectThe configuration related to User objects.
      fileResource Configuration ObjectThe configuration related to File objects.
      postResource Configuration ObjectThe configuration related to Post objects.
      messageResource Configuration ObjectThe configuration related to Message objects.
      channelResource Configuration ObjectThe configuration related to Channel objects.
      + +## Resource Configuration + +<%= json(:config) { |h| + user = h["user"] + h.clear + h.update(user) +} %> + +A Resource Configuration object represents values that only apply to a specific App.net resource. + +### Resource Configuration Fields + + + + + + + + + + + + + + + + + + + + + +
      FieldTypeDescription
      annotation_max_bytesintegerThe maximum number of bytes that can be attached to this type of object as an Annotation.
      text_max_lengthintegerThe maximum number of characters that an instance of this object can be. For User objects, this applies to the User description. This field does not apply to Channel objects.
      + +## How should I use the Configuration object + +The App.net platform has platform-wide limits that all apps must respect. They are enforced at an API level, but they can be useful to have defined as variable in your app's code. Examples are things like: "how long can a Post be" or "how long can annotations be on a Channel object." This endpoint allows you to update your app's configuration so it always has the newest platform-wide configuration values available. + +We recommend: + +1. Ship your application with the current values defined for these configuration values. Persist them when your app launches. +2. At most once per day, query this endpoint. +3. Update any configuration keys to their newest values. We recommend you do this when your app launches or in a cronjob. + +This endpoint should be queried with an access token if you have one. However, if you are creating an app with multiple user accounts you may store this data globally instead of per-user if you'd like. + +## Retrieve the Configuration object + +Returns the current Configuration object. + +*Your application should request this endpoint with a user or app access token if available.* + +<%= endpoint "GET", "config", "None" %> + +#### Example + +> GET https://alpha-api.app.net/stream/0/config + +<%= response(:config) %> diff --git a/content/docs/resources/index.md b/content/docs/resources/index.md index 5e0cd91..79c5d6a 100644 --- a/content/docs/resources/index.md +++ b/content/docs/resources/index.md @@ -75,3 +75,7 @@ Please use https://alpha-api.app.net/ to access the APIs. ## Explore Stream <%= render 'partials/endpoints/explore-stream' %> + +## Configuration + +<%= render 'partials/endpoints/config' %> diff --git a/layouts/default.html b/layouts/default.html index e5fd1dc..b02b127 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -129,6 +129,7 @@
    • Token
    • Place
    • Explore Stream
      • +
    • Configuration
  • Meta
    • diff --git a/layouts/partials/endpoints/config.md b/layouts/partials/endpoints/config.md new file mode 100644 index 0000000..a5eac59 --- /dev/null +++ b/layouts/partials/endpoints/config.md @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + +
    DescriptionMethodPathToken
    Retrieve the Configuration objectGET/stream/0/configNone
    \ No newline at end of file diff --git a/lib/sample_objects.rb b/lib/sample_objects.rb index ac16823..82d9be7 100644 --- a/lib/sample_objects.rb +++ b/lib/sample_objects.rb @@ -200,6 +200,33 @@ def paginated_response(key, &block) USER_SELF_BLACKLIST = ['follows_you', 'you_follow', 'you_muted', 'you_blocked', 'you_can_subscribe', 'you_can_follow'] USER_SELF = USER.reject {|key, value| USER_SELF_BLACKLIST.include?(key) } + + CONFIG = { + "text" => { + "uri_template_length" => { + "post_id" => 9, + "message_id" => 12 + } + }, + "user" => { + "annotation_max_bytes" => 8192, + "text_max_length" => 256 + }, + "file" => { + "annotation_max_bytes" => 8192 + }, + "post" => { + "annotation_max_bytes" => 8192, + "text_max_length" => 256 + }, + "message" => { + "annotation_max_bytes" => 8192, + "text_max_length" => 256 + }, + "channel" => { + "annotation_max_bytes" => 8192 + } + } end include Resources::Helpers From e6d423cdc3e03f784339c9dc02b3cf4cc9971e8d Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Tue, 13 Aug 2013 12:25:13 -0700 Subject: [PATCH 113/231] flesh out explanations a bit --- content/docs/resources/config/index.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/content/docs/resources/config/index.md b/content/docs/resources/config/index.md index edd4ed3..3daa63a 100644 --- a/content/docs/resources/config/index.md +++ b/content/docs/resources/config/index.md @@ -7,7 +7,7 @@ title: "Configuration" * TOC {:toc} -The Configuration object defines platform-wide variables that Apps can use to make sure their behavior is consistent with the platform. +The Configuration object contains variables which define the current behavior of the App.net platform. ## Example Configuration object @@ -102,17 +102,19 @@ A Resource Configuration object represents values that only apply to a specific -## How should I use the Configuration object +## How to use the Configuration object -The App.net platform has platform-wide limits that all apps must respect. They are enforced at an API level, but they can be useful to have defined as variable in your app's code. Examples are things like: "how long can a Post be" or "how long can annotations be on a Channel object." This endpoint allows you to update your app's configuration so it always has the newest platform-wide configuration values available. +The App.net platform has platform-wide limits that all apps must respect. These limits are enforced at an API level, but can be useful to have defined as constants in your app's code, often for the purpose of displaying your user interface. Examples are things like: "how long can a Post be" or "how long can annotations be on a Channel object." This endpoint allows you to update your app's configuration so it always has the newest platform-wide configuration values available. We recommend: -1. Ship your application with the current values defined for these configuration values. Persist them when your app launches. -2. At most once per day, query this endpoint. -3. Update any configuration keys to their newest values. We recommend you do this when your app launches or in a cronjob. +1. Ship your application with a static copy of the configuration object. When your app launches for the first time, persist those static values into your application's preference store (NSUserDefaults or SharedPreferences, etc.) +2. On launch, and at most once per day, poll the configuration endpoint; if it differs from the previously persisted data, update your persisted copy of the configuration object. +3. Always use the values from your persisted configuration. -This endpoint should be queried with an access token if you have one. However, if you are creating an app with multiple user accounts you may store this data globally instead of per-user if you'd like. +This pattern will ensure that no matter whether your application has network connectivity or not, you will have values, even if they are out of date. As the majority of these variables are related to user interface, slightly outdated configuration variables are generally not a problem. + +This endpoint should be queried with an access token if you have one. If you are creating an app which spports with multiple user accounts, you may store this data globally instead of per-user. ## Retrieve the Configuration object From c6de6ea60387ccd4c3027d5295e669a853f1af73 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Tue, 13 Aug 2013 14:57:15 -0700 Subject: [PATCH 114/231] Typo --- content/docs/resources/config/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/config/index.md b/content/docs/resources/config/index.md index 3daa63a..67e7d9d 100644 --- a/content/docs/resources/config/index.md +++ b/content/docs/resources/config/index.md @@ -114,7 +114,7 @@ We recommend: This pattern will ensure that no matter whether your application has network connectivity or not, you will have values, even if they are out of date. As the majority of these variables are related to user interface, slightly outdated configuration variables are generally not a problem. -This endpoint should be queried with an access token if you have one. If you are creating an app which spports with multiple user accounts, you may store this data globally instead of per-user. +This endpoint should be queried with an access token if you have one. If you are creating an app which supports multiple user accounts, you may store this data globally instead of per-user. ## Retrieve the Configuration object From b4e25cb2d54821b9af5e0c54b623cd92fb97d883 Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Thu, 5 Sep 2013 12:22:09 -0700 Subject: [PATCH 115/231] Update readme a bit --- README.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index ad0446b..d215d3c 100644 --- a/README.md +++ b/README.md @@ -2,31 +2,29 @@ This branch (new-docs) of the appdotnet/api-spec repo contains the source for [developers.app.net](http://developers.app.net/) and replaces the docs located on the master branch. -This documentation can be compiled using [nanoc](http://nanoc.stoneship.org/). +This documentation can be compiled using [nanoc](http://nanoc.stoneship.org/). All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a [pull request](http://help.github.com/send-pull-requests/). ## Building the docs -Ruby 1.9 is required to build the site. +Ruby is required to build the site. -To install nanoc and make sure you have all the necessary ruby gems, open a terminal and run +To install nanoc and make sure you have all the necessary ruby gems, open a terminal in the root of the api-spec checkout and run $ bundle install -To compile the docs, run +To compile the docs for the first time, run - $ nanoc + $ bundle exec nanoc Nanoc compiles the site into static files living in `./output`. -Once the docs are compiled, you can view the result using the adsf web server which is part of the install bundle: +In general, the best way to work on the docs is like this: - $ nanoc view - $ open http://localhost:3000 + $ bundle exec nanoc view & + $ bundle exec guard start -If you want to have nanoc autocompile your changes, run - - $ nanoc watch +Guard will run and auto-generate new HTML output when you edit Markdown files, and the nanoc built-in webserver will be available on http://localhost:3000/ If you want to learn more about using nanoc, view the [nanoc documentation](http://nanoc.stoneship.org/docs/1-introduction/). From ac4dced3ab7aa0b43a96f8e25852f9e65ac60ccf Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 11 Sep 2013 11:22:07 -0700 Subject: [PATCH 116/231] Add first stream facet --- content/docs/resources/post/index.md | 27 ++++++++++++++++++++++++++ content/docs/resources/post/streams.md | 4 ++++ lib/helpers.rb | 4 ++++ 3 files changed, 35 insertions(+) diff --git a/content/docs/resources/post/index.md b/content/docs/resources/post/index.md index c806908..dd62096 100644 --- a/content/docs/resources/post/index.md +++ b/content/docs/resources/post/index.md @@ -299,6 +299,33 @@ Where noted, Post endpoints respond to the following query string parameters: Where noted, endpoints that return a stream of Posts additionally respond to [pagination parameters](/docs/basics/pagination). + +## Stream Faceting parameters + +Stream Faceting allows you to filter and query a user's [personalized stream](/docs/resources/post/streams/#retrieve-a-users-personalized-stream) or [unified stream](/docs/resources/post/streams/#retrieve-a-users-unified-stream) with an interface similar to our [Post Search API](/docs/resources/post/search/#search-for-posts). If you use stream faceting, the API will only return recent posts in a user's stream. + +Currently the following stream facets are supported: + + + + + + + + + + + + + + + + + + +
    NameRequired?TypeDescription
    has_oembed_photoOptionalinteger (0 or 1)Only include posts with photo oembed annotations.
    + + ## Sorting Posts Post `id` is the ordering field for multiple posts, not `created_at`. `created_at` is meant to be displayed to users, not to sort Posts. This also makes pagination with `since_id` and `before_id` more straightforward. Posts are presently always returned in reverse chronological order (newest to oldest). As a result, the Posts endpoints will always return the newest posts that meet the requested criteria (e.g. `before_id` and `count`). diff --git a/content/docs/resources/post/streams.md b/content/docs/resources/post/streams.md index 38b0db8..a3dc7f5 100644 --- a/content/docs/resources/post/streams.md +++ b/content/docs/resources/post/streams.md @@ -228,6 +228,8 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current User a <%= general_params_note_for "post" %> +<%= stream_facet_note %> + <%= pagination_note %> <%= endpoint "GET", "posts/stream", "User", "stream" %> @@ -299,6 +301,8 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current user's <%= pagination_note %> +<%= stream_facet_note %> + <%= endpoint "GET", "posts/stream/unified", "User", "stream" %> #### Example diff --git a/lib/helpers.rb b/lib/helpers.rb index 7e19dc5..5defab4 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -50,6 +50,10 @@ def general_params_note_for(type) 'This endpoint responds to general '+type.capitalize+' parameters.' end +def stream_facet_note() + "This endpoint can be Faceted to filter it's results." +end + # feel free to override these from your environment def lanai_hostname() ENV['LANAI_HOSTNAME'] || 'app.net' From d11cc134223b771db94dda4ab8183b0f6222f2ee Mon Sep 17 00:00:00 2001 From: Brian Armstrong Date: Thu, 26 Sep 2013 17:38:00 -0700 Subject: [PATCH 117/231] Channel search --- content/docs/resources/channel/search.md | 101 +++++++++++++++++++++++ layouts/default.html | 1 + layouts/partials/endpoints/channel.md | 6 ++ 3 files changed, 108 insertions(+) create mode 100644 content/docs/resources/channel/search.md diff --git a/content/docs/resources/channel/search.md b/content/docs/resources/channel/search.md new file mode 100644 index 0000000..257145a --- /dev/null +++ b/content/docs/resources/channel/search.md @@ -0,0 +1,101 @@ +--- +title: "Channel Search" +--- + +# Search + +* TOC +{:toc} + +## Search for Channels + +Returns [Channel](/docs/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. net.patter-app.settings. 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 messages scope. + +<%= general_params_note_for "channel" %> Note: Pagination works for all orderings on this endpoint. Be sure to make requests with before_id=max_id or since_id=min_id as usual when paginating the popularity-sorted results. Separate lists of terms by spaces. + +<%= endpoint "GET", "channels/search", "User", "public_messages or messages" %> + +<%= query_params_typed 'General Parameters', [ + + ["order", :optional, "string", "One of: popularity (default), id. Searches of ordering popularity are returned in an order that roughly matches the popularity of the channels."], + +]%> + +<%= query_params_typed 'Search Query Parameters', [ + + ["q", :optional, "string", "Searches any textual fields extracted from channel annotations. We may tweak which annotations and fields are included by this search over time."], + +]%> + + +<%= query_params_typed 'Filter Parameters', [ + ["type", :optional, "string", "Only include channels which were created with a specific channel type"], + ["creator_id", :optional, "string", "Only include channels which were created by a user with a certain id"], + ["tags", :optional, "string", "Only include channels which are tagged with certain tags. This data is extracted from channel annotations"], + +]%> + +#### Example + +> GET https://alpha-api.app.net/stream/0/channels/search?q=kerbal&order=popularity + +~~~ js +{ + "data": [ + ... + { + "counts": { + "messages": 178 + }, + "has_unread": false, + "id": "13797", + "is_inactive": false, + "owner": { + ... + }, + "readers": { + "any_user": false, + "immutable": false, + "public": true, + "user_ids": [], + "you": true + }, + "recent_message_id": "1222525", + "type": "net.patter-app.room", + "writers": { + "any_user": true, + "immutable": false, + "public": false, + "user_ids": [], + "you": true + }, + "you_can_edit": true, + "you_muted": false, + "you_subscribed": true, + "annotations": [ + { + "type": "net.patter-app.settings", + "value": { + "blurb": "Discussion for the wonderful space simulator "Kerbal Space Program." Rocket designs, missions, anecdotes etc. welcome", + "blurb_id": "417309", + "categories": ["fun"], + "name": "Kerbonauts" + } + }, + { + "type": "net.app.core.fallback_url", + "value": { + "url": "http://patter-app.net/room.html?channel=13797" + } + } + ] + } + ], + "meta": { + "code": 200, + "max_id": "1", + "min_id": "1", + "more": false + } +} +~~~ diff --git a/layouts/default.html b/layouts/default.html index b02b127..ca2147a 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -99,6 +99,7 @@
  • Lifecycle
  • Muting
  • Subscriptions
    • +
  • Search
  • Message
      • diff --git a/layouts/partials/endpoints/channel.md b/layouts/partials/endpoints/channel.md index 2f3dfd3..69a1344 100644 --- a/layouts/partials/endpoints/channel.md +++ b/layouts/partials/endpoints/channel.md @@ -98,5 +98,11 @@ /stream/0/users/me/channels/muted User + + Search for Channels + GET + /stream/0/channels/search + Any + From 914c5cbae9e0be3514d4313b983446014440859d Mon Sep 17 00:00:00 2001 From: Brian Armstrong Date: Thu, 26 Sep 2013 17:39:51 -0700 Subject: [PATCH 118/231] Wrong token type --- layouts/partials/endpoints/channel.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/layouts/partials/endpoints/channel.md b/layouts/partials/endpoints/channel.md index 69a1344..f6129b3 100644 --- a/layouts/partials/endpoints/channel.md +++ b/layouts/partials/endpoints/channel.md @@ -102,7 +102,7 @@ Search for Channels GET /stream/0/channels/search - Any + User From 5492fc81bacf7bc8f1896f3a3d7adba70fc51cd6 Mon Sep 17 00:00:00 2001 From: Andrew Knapp Date: Thu, 3 Oct 2013 14:29:22 -0700 Subject: [PATCH 119/231] Add in a favicon to the docs --- layouts/default.html | 1 + 1 file changed, 1 insertion(+) diff --git a/layouts/default.html b/layouts/default.html index ca2147a..a43711e 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -8,6 +8,7 @@ + From 37d0f982e91a439d7ee1cdfaeaed7a4e5fccdc10 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 3 Oct 2013 16:25:28 -0700 Subject: [PATCH 120/231] Fix header space --- static/css/style.css | 1 + 1 file changed, 1 insertion(+) diff --git a/static/css/style.css b/static/css/style.css index 5514ffc..3ee6f90 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -109,6 +109,7 @@ ul.nav-list ul.nav-list ul.nav-list li a { padding-left: 50px; } +.new-nav .nav.header, .nav.header { margin-bottom: 0; border-bottom: none; From ed2c174fe342b0772eb8b13ba19d92d9243f1b0e Mon Sep 17 00:00:00 2001 From: Brian Armstrong Date: Fri, 4 Oct 2013 13:52:58 -0700 Subject: [PATCH 121/231] New channel search args --- content/docs/resources/channel/search.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/resources/channel/search.md b/content/docs/resources/channel/search.md index 257145a..c98ac8b 100644 --- a/content/docs/resources/channel/search.md +++ b/content/docs/resources/channel/search.md @@ -17,7 +17,7 @@ Returns [Channel](/docs/resources/channel/) objects which match a given search q <%= query_params_typed 'General Parameters', [ - ["order", :optional, "string", "One of: popularity (default), id. Searches of ordering popularity are returned in an order that roughly matches the popularity of the channels."], + ["order", :optional, "string", "One of: popularity (default), id, or activity. Searches of ordering popularity are returned in an order that roughly matches the popularity of the channels. activity searches will order results roughly by time of last message (precise sorting of very recent messages is not guaranteed)."], ]%> @@ -32,6 +32,8 @@ Returns [Channel](/docs/resources/channel/) objects which match a given search q ["type", :optional, "string", "Only include channels which were created with a specific channel type"], ["creator_id", :optional, "string", "Only include channels which were created by a user with a certain id"], ["tags", :optional, "string", "Only include channels which are tagged with certain tags. This data is extracted from channel annotations"], + ["is_private", :optional, "boolean", "Only include channels which have any_user set to false for read and write ACLs"], + ["is_public", :optional, "boolean", "Only include channels which have public set to true for read ACLs"], ]%> From 8ae2f79342ca3359e7d3e7d5cddb92cec26a6d33 Mon Sep 17 00:00:00 2001 From: Brian Armstrong Date: Fri, 4 Oct 2013 13:55:12 -0700 Subject: [PATCH 122/231] clarify is_private flag --- content/docs/resources/channel/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/channel/search.md b/content/docs/resources/channel/search.md index c98ac8b..4c1fc61 100644 --- a/content/docs/resources/channel/search.md +++ b/content/docs/resources/channel/search.md @@ -32,7 +32,7 @@ Returns [Channel](/docs/resources/channel/) objects which match a given search q ["type", :optional, "string", "Only include channels which were created with a specific channel type"], ["creator_id", :optional, "string", "Only include channels which were created by a user with a certain id"], ["tags", :optional, "string", "Only include channels which are tagged with certain tags. This data is extracted from channel annotations"], - ["is_private", :optional, "boolean", "Only include channels which have any_user set to false for read and write ACLs"], + ["is_private", :optional, "boolean", "Only include channels which have any_user and public set to false for read and write ACLs"], ["is_public", :optional, "boolean", "Only include channels which have public set to true for read ACLs"], ]%> From 587f763773b3e4ff6efd17644affb432a273684d Mon Sep 17 00:00:00 2001 From: Brian Armstrong Date: Fri, 4 Oct 2013 15:25:33 -0700 Subject: [PATCH 123/231] got min_id/max_id mixed up --- content/docs/resources/channel/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/channel/search.md b/content/docs/resources/channel/search.md index 4c1fc61..e64b92c 100644 --- a/content/docs/resources/channel/search.md +++ b/content/docs/resources/channel/search.md @@ -11,7 +11,7 @@ title: "Channel Search" Returns [Channel](/docs/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. net.patter-app.settings. 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 messages scope. -<%= general_params_note_for "channel" %> Note: Pagination works for all orderings on this endpoint. Be sure to make requests with before_id=max_id or since_id=min_id as usual when paginating the popularity-sorted results. Separate lists of terms by spaces. +<%= 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. <%= endpoint "GET", "channels/search", "User", "public_messages or messages" %> From 6a9a7fcaf24113f90443611b387d683d2a63918b Mon Sep 17 00:00:00 2001 From: Rob Brambley Date: Sun, 20 Oct 2013 10:20:42 -0700 Subject: [PATCH 124/231] left out an o, yo. --- content/docs/resources/post/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/post/search.md b/content/docs/resources/post/search.md index 2209676..99d1d90 100644 --- a/content/docs/resources/post/search.md +++ b/content/docs/resources/post/search.md @@ -52,7 +52,7 @@ Returns [Post](/docs/resources/post/) objects which match a given search query. ["has_oembed_photo", :optional, "int (0 or 1)", "Only include posts with photo oembed annotations"], ["has_oembed_video", :optional, "int (0 or 1)", "Only include posts with video (not html5video) oembed annotations"], ["has_oembed_html5video", :optional, "int (0 or 1)", "Only include posts with html5video oembed annotations"], - ["has_oembed_rich", :optional, "int (0 or 1)", "Only include posts with rich oembed anntations"], + ["has_oembed_rich", :optional, "int (0 or 1)", "Only include posts with rich oembed annotations"], ["language", :optional, "string", "Only include posts with a certain language tagged with the net.app.core.language annotation."], ["client_id", :optional, "string", "Only include posts created by a certain app. Use the alphanumeric client_id"], From 6250ca996cd0b15eb9cf7caf99880c91044e38ed Mon Sep 17 00:00:00 2001 From: Maximillian Dornseif Date: Thu, 24 Oct 2013 09:24:17 +0200 Subject: [PATCH 125/231] Fixing link to privacy preferences. --- content/docs/basics/messaging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/basics/messaging.md b/content/docs/basics/messaging.md index 054e407..1b61672 100644 --- a/content/docs/basics/messaging.md +++ b/content/docs/basics/messaging.md @@ -40,7 +40,7 @@ In addition, an App access token has read access to a Channel and its contents w Users indicate their interest in a given channel by subscribing to it. When a channel is created, no one is subscribed to it. -[Private message channels](/docs/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription preferences](https://account.app.net/settings/messaging-permissions/). +[Private message channels](/docs/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription/privacy preferences](https://account.app.net/settings/privacy/). To get this same behavior for non-pm channels, you include the key `auto_subscribe: true` when you create or update the Channel. This will auto-subscribe all the users on the ACLs (according to their preferences). From 0a5ee8e3d2810d77f6b76b6a86b8a6aa24455ec8 Mon Sep 17 00:00:00 2001 From: Nicole Hedley Date: Thu, 24 Oct 2013 15:58:06 -0700 Subject: [PATCH 126/231] Edited password flow request obtain authorization --- content/docs/authentication/flows/password.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/authentication/flows/password.md b/content/docs/authentication/flows/password.md index dc0660f..aa3e7e1 100644 --- a/content/docs/authentication/flows/password.md +++ b/content/docs/authentication/flows/password.md @@ -13,7 +13,7 @@ This is referred to as the Resource Owner Password Credential flow in the OAuth ## Obtaining approval to use the password flow -**Your application must be specifically approved to use this flow.** To obtain authorization, please email [password-auth@app.net](mailto:password-auth@app.net) from the email address associated with your developer account and include your application's `client_id`, your username, and an explanation of your situation (e.g. "I am building a native app for iOS"). +**Your application must be specifically approved to use this flow.** To obtain authorization, visit the account page for your app and click **Request approval for password flow**. You will need to provide an explanation of your situation and then click the **Submit Request** button to complete your request for authroization. When your request has been approved you will receive an email with your password grant secret. The password grant secret token will also be available on your account page. ## Rules From 502940bea9d5eceed98ceea97bca3a22bd72a741 Mon Sep 17 00:00:00 2001 From: Nicole Hedley Date: Thu, 24 Oct 2013 16:11:21 -0700 Subject: [PATCH 127/231] Updated request password flow obtain authorization docs. --- content/docs/authentication/flows/password.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/authentication/flows/password.md b/content/docs/authentication/flows/password.md index aa3e7e1..ca31252 100644 --- a/content/docs/authentication/flows/password.md +++ b/content/docs/authentication/flows/password.md @@ -13,7 +13,7 @@ This is referred to as the Resource Owner Password Credential flow in the OAuth ## Obtaining approval to use the password flow -**Your application must be specifically approved to use this flow.** To obtain authorization, visit the account page for your app and click **Request approval for password flow**. You will need to provide an explanation of your situation and then click the **Submit Request** button to complete your request for authroization. When your request has been approved you will receive an email with your password grant secret. The password grant secret token will also be available on your account page. +**Your application must be specifically approved to use this flow.** To obtain authorization, go to your [App.net developer dashboard](https://account.app.net/developer/apps/), select your app, and click **Request approval for password flow**. You will need to provide an explanation of your situation and then click the **Submit Request** button to complete your request for authroization. When your request has been approved you will receive an email with your password grant secret. The password grant secret token will also be available on your account page. ## Rules From 18bb7b4fff0b05e98e2c42cc34e28ace105d5075 Mon Sep 17 00:00:00 2001 From: Nicole Hedley Date: Fri, 25 Oct 2013 09:42:06 -0700 Subject: [PATCH 128/231] Fixed typo in password flow --- content/docs/authentication/flows/password.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/authentication/flows/password.md b/content/docs/authentication/flows/password.md index ca31252..34ec6d6 100644 --- a/content/docs/authentication/flows/password.md +++ b/content/docs/authentication/flows/password.md @@ -13,7 +13,7 @@ This is referred to as the Resource Owner Password Credential flow in the OAuth ## Obtaining approval to use the password flow -**Your application must be specifically approved to use this flow.** To obtain authorization, go to your [App.net developer dashboard](https://account.app.net/developer/apps/), select your app, and click **Request approval for password flow**. You will need to provide an explanation of your situation and then click the **Submit Request** button to complete your request for authroization. When your request has been approved you will receive an email with your password grant secret. The password grant secret token will also be available on your account page. +**Your application must be specifically approved to use this flow.** To obtain authorization, go to your [App.net developer dashboard](https://account.app.net/developer/apps/), select your app, and click **Request approval for password flow**. You will need to provide an explanation of your situation and then click the **Submit Request** button to complete your request for authorization. When your request has been approved you will receive an email with your password grant secret. The password grant secret token will also be available on your account page. ## Rules From c19238bc1a25fb690ae0308f342bc96acaa6ff2d Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Tue, 29 Oct 2013 09:39:45 -0700 Subject: [PATCH 129/231] Fix messaging permissions link --- content/docs/basics/messaging.md | 2 +- content/docs/resources/message/lifecycle.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/basics/messaging.md b/content/docs/basics/messaging.md index 054e407..db4dc77 100644 --- a/content/docs/basics/messaging.md +++ b/content/docs/basics/messaging.md @@ -40,7 +40,7 @@ In addition, an App access token has read access to a Channel and its contents w Users indicate their interest in a given channel by subscribing to it. When a channel is created, no one is subscribed to it. -[Private message channels](/docs/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription preferences](https://account.app.net/settings/messaging-permissions/). +[Private message channels](/docs/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription preferences](https://account.app.net/settings/privacy/#messaging). To get this same behavior for non-pm channels, you include the key `auto_subscribe: true` when you create or update the Channel. This will auto-subscribe all the users on the ACLs (according to their preferences). diff --git a/content/docs/resources/message/lifecycle.md b/content/docs/resources/message/lifecycle.md index 2db69fb..c005675 100644 --- a/content/docs/resources/message/lifecycle.md +++ b/content/docs/resources/message/lifecycle.md @@ -19,7 +19,7 @@ If you want to test how your text will be processed you can use the [text proces #### Creating Private Messages for use with net.app.core.pm Channels -To create private group messages for use in `net.app.core.pm` channels, you can specify the special `channel_id` of `pm`. With this parameter, the server will look for an extra field in the provided message object called `destinations` which is a list of user ids to send this message to. If a private message channel already exists between this group of users, its `channel_id` will be reused. Otherwise, a new channel will be created and the users specified in the `destinations` list will be auto-subscribed (according to their [subscription preferences](https://account.app.net/settings/messaging-permissions/)) and able to write to that channel. Note that the `destinations` value may include user ids in the form of "@username" or integer id. +To create private group messages for use in `net.app.core.pm` channels, you can specify the special `channel_id` of `pm`. With this parameter, the server will look for an extra field in the provided message object called `destinations` which is a list of user ids to send this message to. If a private message channel already exists between this group of users, its `channel_id` will be reused. Otherwise, a new channel will be created and the users specified in the `destinations` list will be auto-subscribed (according to their [subscription preferences](https://account.app.net/settings/privacy/#messaging)) and able to write to that channel. Note that the `destinations` value may include user ids in the form of "@username" or integer id. <%= general_params_note_for "message" %> From bb54c7da50d1012b21c32f800e11276bea65fa55 Mon Sep 17 00:00:00 2001 From: Bryan Clark Date: Tue, 5 Nov 2013 09:16:11 -0800 Subject: [PATCH 130/231] Fix missing link to Create Private Message endpoint In the Private Messages section, the end of the paragraph includes a bit of Markdown that looks like it's missing its link: ``` This Channel type differs from others in that it is designed to provide a simple, combined API for Channel creation, euse and Message sending. You can only create net.app.core.pm Channels via the [create private message Channel endpoint]. ``` Looks like that link should point to: http://developers.app.net/docs/resources/message/lifecycle/#create-a-message --- content/docs/resources/channel/index.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/docs/resources/channel/index.md b/content/docs/resources/channel/index.md index 414e804..c8f629c 100644 --- a/content/docs/resources/channel/index.md +++ b/content/docs/resources/channel/index.md @@ -233,7 +233,8 @@ This Channel type is for private messages between 2 or more people. As a core Ch - Private message Channels enforce that there is at least one non-owner user_id in the `writers` ACL and that both ACLs are immutable. - Messages with the `machine_only` flag set are disallowed (though, of course, annotations are permitted when accompanied with text.) -- This Channel type differs from others in that it is designed to provide a simple, combined API for Channel creation, reuse and Message sending. You can only create `net.app.core.pm` Channels via the [create private message Channel endpoint]. +- This Channel type differs from others in that it is designed to provide a simple, combined API for Channel creation, reuse and Message sending. You can only create `net.app.core.pm` Channels via the [create private message Channel endpoint](http://developers.app.net/docs/resources/message/lifecycle/#create-a-message +). You can create arbitrary Channel types which do not have these restrictions (but are able to maintain the same level of privacy.) From 6c550412b7c9415516d7b7512d8154188bef53c9 Mon Sep 17 00:00:00 2001 From: Bryan Clark Date: Sat, 9 Nov 2013 13:38:04 -0800 Subject: [PATCH 131/231] Fixed broken link --- content/docs/resources/app-stream/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/app-stream/index.md b/content/docs/resources/app-stream/index.md index 7b9a260..b6db44b 100644 --- a/content/docs/resources/app-stream/index.md +++ b/content/docs/resources/app-stream/index.md @@ -205,7 +205,7 @@ One of the main uses of an App Stream is to send notifications to users about wh App.net recognizes that there are some standard notifications that many clients send to users. To make sure users don't get notifications from other users they've muted or blocked, App.net provides some extra information with each streaming event. -For each streaming event, App.net generates a list of every user who would be notified using the [standard notifications](#what-are-the-standard-notifications). Then, App.net provides a list of user ids who should not receive a notification from this event. +For each streaming event, App.net generates a list of every user who would be notified using the [standard notifications](#standard-notification-types). Then, App.net provides a list of user ids who should not receive a notification from this event. If your app only sends standard notifications, you won't have to keep lists of who a user has muted or blocked. Instead, when you receive a message from the Streaming API: From e320b7795524f64ac4444e763828f097a4769f2e Mon Sep 17 00:00:00 2001 From: Bryan Clark Date: Tue, 12 Nov 2013 20:34:47 -0800 Subject: [PATCH 132/231] Fix: broken links in App Stream sample objects Links were using hyphens instead of underscores. Fixed! --- content/docs/resources/app-stream/index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/resources/app-stream/index.md b/content/docs/resources/app-stream/index.md index b6db44b..40e6474 100644 --- a/content/docs/resources/app-stream/index.md +++ b/content/docs/resources/app-stream/index.md @@ -241,13 +241,13 @@ An App Stream can listen for the following object types: * [post](#post): Sent for new posts, replies, reposts, and post deletions * [star](#star): Sent when a user stars a post -* [user_follow](#user-follow): Sent when a user begins following or unfollows another user +* [user_follow](#user_follow): Sent when a user begins following or unfollows another user * [mute](#mute): Sent when a user who has authorized your app mutes or unmutes another user * [block](#block): Sent when a user who has authorized your app blocks or unblocks another user -* [stream_marker](#stream-marker): Sent when a stream marker is updated +* [stream_marker](#stream_marker): Sent when a stream marker is updated * [message](#message): Sent for new objects, replies, and message deletions * [channel](#channel): Sent when a channel is created or updated -* [channel_subscription](#channel-subscription): Sent when a user subscribes or unsubscribes to a channel +* [channel_subscription](#channel_subscription): Sent when a user subscribes or unsubscribes to a channel * [token](#token): Sent when a user authorizes, changes scopes for, or deauthorizes an app * [file](#file): Sent when a user creates a file, updates a file, or deletes a file From 9d1297f5a1a4c7f206dd168f8a9b418361d52554 Mon Sep 17 00:00:00 2001 From: Brian Armstrong Date: Thu, 14 Nov 2013 10:54:04 -0800 Subject: [PATCH 133/231] has_location refers to net.app.core.geolocation --- content/docs/resources/post/search.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/resources/post/search.md b/content/docs/resources/post/search.md index 99d1d90..8c199d8 100644 --- a/content/docs/resources/post/search.md +++ b/content/docs/resources/post/search.md @@ -45,7 +45,7 @@ Returns [Post](/docs/resources/post/) objects which match a given search query. ["is_reply", :optional, "int (0 or 1)", "Only include replies"], ["is_directed", :optional, "int (0 or 1)", "Only include posts with leading mentions, i.e., posts which were directed at other users"], - ["has_location", :optional, "int (0 or 1)", "Only include posts containing geo coordinates, i.e., tagged with the net.app.core.location annotation"], + ["has_location", :optional, "int (0 or 1)", "Only include posts containing geo coordinates, i.e., tagged with the net.app.core.geolocation annotation"], ["has_checkin", :optional, "int (0 or 1)", "Only include posts containing place IDs, i.e., tagged with the net.app.core.checkin annotation"], ["is_crosspost", :optional, "int (0 or 1)", "Only include posts which are crossposts, i.e., tagged with the net.app.core.crosspost annotation"], ["has_attachment", :optional, "int (0 or 1)", "Only include posts with file attachments"], From 9f8746e113fe4742d72eba5d1140d0071a1ace9c Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 14 Nov 2013 20:43:48 -0800 Subject: [PATCH 134/231] Adding in some guides --- content/docs/guides/create-an-app.md | 80 ++++++++++++++++++++ content/docs/guides/send-a-broadcast.md | 97 +++++++++++++++++++++++++ static/css/style.css | 8 ++ 3 files changed, 185 insertions(+) create mode 100644 content/docs/guides/create-an-app.md create mode 100644 content/docs/guides/send-a-broadcast.md diff --git a/content/docs/guides/create-an-app.md b/content/docs/guides/create-an-app.md new file mode 100644 index 0000000..3896b4b --- /dev/null +++ b/content/docs/guides/create-an-app.md @@ -0,0 +1,80 @@ +--- +title: "Create an App" +--- + +# Getting Started With Development + +To start accessing parts of the API that require authentication you will need an **access token**. The easiest way to create an access token is to register an app in your [account dashboard](https://account.app.net/settings/). + +* TOC +{:toc} + +## Creating an App + +Start by visiting [account.app.net/settings/](https://account.app.net/settings/). + +![Your Account Dashboard](https://files.app.net/01q1LmOn.png) + +Clicking on [Your Apps](https://account.app.net/developer/apps/) in the bottom left hand corner. Will take you to your app dashboard. + +![Your Apps Dashboard](https://files.app.net/01qsFuCH.png) + +This is what you will see if you haven't created any apps. To start the process of registering your app click on [Create one here](https://account.app.net/developer/app/create/). + +Next, we will see the App Create page. + +![Create Your App](https://files.app.net/01qdir2Q.png) + +You will be able to change all of this later, but start by giving your app a name that is unique to you, or your organization. + +Enter a website that is most closely related to this app. If doesn't make sense for you to enter a website feel free to enter in your Alpha profile URL. (https://app.net/). This will let others know who is responsible for this app. + +The **Callback URL** is prefilled with http://localhost:8000 as a convince for local development. The Callback URL will be used when you [authenticate your app](/docs/authentication/) later. + +When you are satisfied with the information you have entered click create. + +You will see something like this once you have created your app. + +![Your New App](https://files.app.net/01qb1llv.png) + +As you can see we have blurred out the **client secret**, but this is roughly what your app will look like once it has been created. + +From here you could add additional callback URL's for different environments. As well as update your apps information at any time. + +You can also generate your self an access token. + +## Generating an Access Token + +There are a few ways to get an access token, but the easiest way to get an access token for personal use is to generate one from your app detail page. + +To see a list of your current apps visit [account.app.net/settings/developer/.](https://account.app.net/settings/developer/) + +![Your Apps Dashboard](https://files.app.net/01qlWgpd.png) + +Find the app you would like to generate an access token for and click on the name. You should now see your app detail page. + +![Generate a token](https://files.app.net/01q9srKw.png) + +From this screen, if you look at the second block you will see a link: 'Generate a user token for yourself'. Click on that link, and you will see a page like this. + +![Scope Selection Screen](https://files.app.net/01qv_Geq.png) + +This is the scope authorization screen. If you have already generated a token this page may have some permissions checked already otherwise there won't be any. + +To find out more about scopes your can [read the scope docs.](/docs/authentication/#scopes) + +Once you have determined which scopes you will need select them in the form and then click generate. + +![Your new access token](https://files.app.net/01lz9mQt.png) + +Now you should see an access token in a textbox, then you can copy and use in a client library, or even from curl. + +
      + Remember: An access token is just like a password. It will allow applications to interact with the API on your behalf. So, keep it secret. +
      + + + + + + diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md new file mode 100644 index 0000000..b85bec3 --- /dev/null +++ b/content/docs/guides/send-a-broadcast.md @@ -0,0 +1,97 @@ +--- +title: "Send A Broadcast From The API" +--- + +# Send a broadcast from the API + +
      +To start sending broadcasts from the API you will need an access token. Read our guide an creating an app to get an access token. +
      + +Broadcast channels are mean't for low-volume high-importance updates that users are interested in. Because broadcasts are built on top of our existing [Channels](), and [Messages]() API there isn't a lot of new stuff you need to know. In this guide we will go over the specfics of creating broadcast channels, and broadcast messages. + +A broadcast channel has a type if `net.app.core.broadcast` and a metadata annotation. A broadcast is a message with a type of `net.app.core.broadcast.message`. + +While there are no hard limits now, + +* TOC +{:toc} + +## Creating a Broadcast Channel + +Before you create your channel you should come up with a unique, compelling title and description for your channel. Users will use this information to decide if they want to subscribe to your channel, or not, so take an extra moment. + +Once you know your information we can construct a JSON object that we will send to the API to create a broadcast channel. + +Lets say we are going to create a broadcast channel for a food truck called Mikhail Borscht. We are creating a channel so that we can send a broadcast every time we setup our truck. This will immediately update our customers as to where we are and they can make the decision to come eat at our truck. + +We might title this channel: + + Mikhail Borscht Truck Location Updates. + +A good description might be: + + Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you. + +Now that we know what our meta data will be we can start building our channel definition. We will start with our metadata annotation. + +~~~ js +channel = { + "annotations": { + "type": "net.app.core.broadcast", + "value": { + "title": "Mikhail Borscht Truck Location Updates.", + "description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you." + } + } +} +~~~ + +But, we aren't done. There are a couple of other decisions we need to make. First, while channels can be private, this channel will be public. Public means anyone, even people who aren't App.net users, will be able to read this channel, and receive broadcasts. Also, since this is public channel, we don't want anyone to accidentally mark it as private so we are going to make this channel immutable. Making an ACL immutable means you won't be able to change it after you create it. We will need to add some data to the channel definition to make this so. + +~~~ js +channel = { + "readers": { + "public": true, + "immutable": true, + }, + "annotations": { + "type": "net.app.core.broadcast", + "value": { + "title": "Mikhail Borscht Truck Location Updates.", + "description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you." + } + } +} +~~~ + +Finally, we need to add one more ACL to determine who can edit this channel. Being able to edit this channel means they can change the channel meta data as well as send broadcasts to subscribers. We are only going to let two people send broadcasts to our channel, but we are going to make the editors mutable so we can change this in the future. + +~~~ js +channel = { + "readers": { + "public": true, + "immutable": true, + }, + "editors": { + "user_ids": ['@samsharp', '@sfborscht'], + "immutable": false, + }, + "annotations": { + "type": "net.app.core.broadcast", + "value": { + "title": "Mikhail Borscht Truck Location Updates.", + "description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you." + } + } +} +~~~ + +Okay, now we are ready to create our broadcast channel. + + + + + + + diff --git a/static/css/style.css b/static/css/style.css index 3ee6f90..99a7166 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -230,4 +230,12 @@ pre code div .gd,.highlight div .gd .x,.highlight div .gi,.highlight div .gi .x p code { word-break: break-all; white-space: normal; +} + +img { + max-width: 90%; + margin: 25px auto 50px auto; + display: block; + padding: 5px; + background-color: #aaa; } \ No newline at end of file From f47830a2e3a2036a26982536d0f9988fc43cafdb Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Mon, 18 Nov 2013 11:02:20 -0800 Subject: [PATCH 135/231] Fleshing out send a broadcast --- content/docs/guides/create-an-app.md | 19 +- content/docs/guides/send-a-broadcast.md | 226 ++++++++++++++++++++---- static/css/style.css | 19 +- 3 files changed, 215 insertions(+), 49 deletions(-) diff --git a/content/docs/guides/create-an-app.md b/content/docs/guides/create-an-app.md index 3896b4b..2e66413 100644 --- a/content/docs/guides/create-an-app.md +++ b/content/docs/guides/create-an-app.md @@ -21,15 +21,15 @@ Clicking on [Your Apps](https://account.app.net/developer/apps/) in the bottom l This is what you will see if you haven't created any apps. To start the process of registering your app click on [Create one here](https://account.app.net/developer/app/create/). -Next, we will see the App Create page. +Next, you will see the App Create page. ![Create Your App](https://files.app.net/01qdir2Q.png) You will be able to change all of this later, but start by giving your app a name that is unique to you, or your organization. -Enter a website that is most closely related to this app. If doesn't make sense for you to enter a website feel free to enter in your Alpha profile URL. (https://app.net/). This will let others know who is responsible for this app. +Enter a website that is most closely related to this app. If it doesn't make sense for you to enter a website feel free to enter in your Alpha profile URL. (https://app.net/). This will let others know who is responsible for this app. -The **Callback URL** is prefilled with http://localhost:8000 as a convince for local development. The Callback URL will be used when you [authenticate your app](/docs/authentication/) later. +The **Callback URL** is prefilled with http://localhost:8000 as a convenience for local development. The Callback URL will be used when you [authenticate your app](/docs/authentication/) later. When you are satisfied with the information you have entered click create. @@ -37,7 +37,7 @@ You will see something like this once you have created your app. ![Your New App](https://files.app.net/01qb1llv.png) -As you can see we have blurred out the **client secret**, but this is roughly what your app will look like once it has been created. +As you can see the **client secret** is blurred, but this is roughly what your app will look like once it has been created. From here you could add additional callback URL's for different environments. As well as update your apps information at any time. @@ -45,7 +45,7 @@ You can also generate your self an access token. ## Generating an Access Token -There are a few ways to get an access token, but the easiest way to get an access token for personal use is to generate one from your app detail page. +There are a few ways to get an access token, but the easiest way to get an access token for personal use or experimentation is to generate one from your app detail page. To see a list of your current apps visit [account.app.net/settings/developer/.](https://account.app.net/settings/developer/) @@ -73,6 +73,15 @@ Now you should see an access token in a textbox, then you can copy and use in a Remember: An access token is just like a password. It will allow applications to interact with the API on your behalf. So, keep it secret.
    +## What's Next? + +Now that you have an access token you can use it to access authenticated parts of the API. + +You could: + +* [Send a broadcast](/docs/guides/send-a-broadcast/) + +Or, you could build something completely new. Let us know what it is if you do. diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index b85bec3..cfea403 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -2,92 +2,240 @@ title: "Send A Broadcast From The API" --- -# Send a broadcast from the API +# Send a broadcast using the API
    To start sending broadcasts from the API you will need an access token. Read our guide an creating an app to get an access token.
    -Broadcast channels are mean't for low-volume high-importance updates that users are interested in. Because broadcasts are built on top of our existing [Channels](), and [Messages]() API there isn't a lot of new stuff you need to know. In this guide we will go over the specfics of creating broadcast channels, and broadcast messages. +Broadcast channels are mean't for low-volume high-value updates that users are interested in. Because broadcasts are built on top of our existing [Channels](/docs/resources/channel/), and [Messages](/docs/resources/message/) API there isn't much new stuff you need to know. In this guide we will go over the specifics of creating a Broadcast Channel and a Broadcast. -A broadcast channel has a type if `net.app.core.broadcast` and a metadata annotation. A broadcast is a message with a type of `net.app.core.broadcast.message`. - -While there are no hard limits now, +While you can do all of this using our API you don't have to. We have [publishers tools](https://directory.app.net/broadcast/manage/) to help you quickly get started. * TOC {:toc} -## Creating a Broadcast Channel - -Before you create your channel you should come up with a unique, compelling title and description for your channel. Users will use this information to decide if they want to subscribe to your channel, or not, so take an extra moment. +## Create a Broadcast Channel -Once you know your information we can construct a JSON object that we will send to the API to create a broadcast channel. +Before you create your channel you should come up with a compelling title and description for your channel. Users will use this information to decide if they want to subscribe to your channel. Take an extra moment before you dive in. Also, keep in mind that users will be able to see how often your Broadcast Channel updates and may choose to not subscribe to high volume channels. -Lets say we are going to create a broadcast channel for a food truck called Mikhail Borscht. We are creating a channel so that we can send a broadcast every time we setup our truck. This will immediately update our customers as to where we are and they can make the decision to come eat at our truck. +For this example, lets say we are going to create a Broadcast Channel for a food truck called Mikhail Borscht. We want to send a Broadcast every time we setup our truck. Using Broadcasts we will immediately be able to inform our customers of our location, our specials for the day, or anything that is of a timely nature. We might title this channel: - Mikhail Borscht Truck Location Updates. + Mikhail Borscht Truck Location Updates A good description might be: - Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you. + Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you and what our specials for the day will be. -Now that we know what our meta data will be we can start building our channel definition. We will start with our metadata annotation. +Now that we have decided on a title and description we can start constructing a channel object that we will send to the API to create a broadcast channel. -~~~ js +**You can create channels using the API, but it might be easier to create your channel using our [publisher tools](https://directory.app.net/broadcast/manage/) instead.** + +It's a good idea to start creating a channel object in a way that you can easily serialize to a JSON string. In python that might be a dict, and in JavaScript that might be an object literal. Pick the one that is right for your language. + +The first part of our channel definition will be putting our title and description into an appropriate [annotation](/docs/meta/annotations/). Also, Broadcast Channels are a special type of of Channel, they have the type `net.app.core.broadcast` we will be adding that to our channel object as well. + +~~~ python channel = { - "annotations": { - "type": "net.app.core.broadcast", + "type": "net.app.core.broadcast", + "annotations": [{ + "type": "net.app.core.broadcast.metadata", "value": { "title": "Mikhail Borscht Truck Location Updates.", "description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you." } - } + }] } ~~~ -But, we aren't done. There are a couple of other decisions we need to make. First, while channels can be private, this channel will be public. Public means anyone, even people who aren't App.net users, will be able to read this channel, and receive broadcasts. Also, since this is public channel, we don't want anyone to accidentally mark it as private so we are going to make this channel immutable. Making an ACL immutable means you won't be able to change it after you create it. We will need to add some data to the channel definition to make this so. +We set our annotation to a type of `net.app.core.broadcast.metadata`. Then we set the value of the annotation to our title and description. Now anyone that can access the API can also know what this broadcast channel is about. -~~~ js +But, we aren't done creating our channel object. Next, we need to decide who can read our broadcasts, and who can send send broadcasts. + +To do that we are going to add two [ACL's](/docs/resources/channel/#acl) to our channel object. A readers ACL, and an editors ACL. + +This channel will be public. Public means anyone, even people who aren't App.net users, will be able to read from this Broadcast Channel. Also, since it won't make sense for the public nature of this channel to change and we don't want anyone to accidentally mark it as private, we are going to make this channel's readers ACL as immutable. + +Marking an ACL immutable means we won't be able to change it after we create it. Once we have added our readers ACL our channel object should look like this. + +~~~ python channel = { + "type": "net.app.core.broadcast", "readers": { - "public": true, - "immutable": true, + "public": True, + "immutable": True, }, - "annotations": { - "type": "net.app.core.broadcast", - "value": { - "title": "Mikhail Borscht Truck Location Updates.", - "description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you." - } - } + "annotations": [{ + ... + }] } ~~~ -Finally, we need to add one more ACL to determine who can edit this channel. Being able to edit this channel means they can change the channel meta data as well as send broadcasts to subscribers. We are only going to let two people send broadcasts to our channel, but we are going to make the editors mutable so we can change this in the future. +We need to add one more ACL to determine who can edit this channel. Being able to edit this channel means they can change the channel metadata and send broadcasts. We are only going mark two users as editors, but we are going to make the editors ACL mutable so we can change this in the future. Our updated channel object should now look something like this. -~~~ js +~~~ python channel = { + "type": "net.app.core.broadcast", "readers": { - "public": true, - "immutable": true, + ... }, "editors": { "user_ids": ['@samsharp', '@sfborscht'], - "immutable": false, + "immutable": False, }, - "annotations": { - "type": "net.app.core.broadcast", + "annotations": [{ + ... + }] +} +~~~ + +We are now ready to create our broadcast channel. For the purposes of this demo we are going to use curl, but you should checkout the client libraries page and use a language specific library. + +~~~ sh +curl -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" \ +-d '{"annotations": [{"type": "net.app.core.broadcast.metadata", "value": {"description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you.", "title": "Mikhail Borscht Truck Location Updates."}}], "type": "net.app.core.broadcast", "editors": {"user_ids": ["@samsharp", "@sfborscht"], "immutable": false}, "readers": {"public": true, "immutable": true}}' \ +https://alpha-api.app.net/stream/0/channels +~~~ + +We will get back our channel resource. You will see that a bunch of information has been added into our channel. Our new channel also has an `id`. We can use that to address this channel in the future. + +~~~ js +{ + "meta": { + "code": 200 + }, + "data": { + "id": "33990", + "type": "net.app.core.broadcast", + "counts": { + "subscribers": 1, + "messages": 0 + }, + "owner": { + "name": "Sam Sharp", + ... + }, + "is_inactive": false, + "readers": { + "immutable": true, + "you": true, + "any_user": false, + "user_ids": [], + "public": true + }, + "you_muted": false, + "you_can_edit": true, + "has_unread": false, + "editors": { + "immutable": false, + "you": true, + "any_user": false, + "user_ids": [ + "190195" + ], + "public": false + }, + "writers": { + "immutable": false, + "you": true, + "any_user": false, + "user_ids": [], + "public": false + }, + "you_subscribed": true + } +} +~~~ + +We have now created a channel. We can continue to administer this channel via API, or we could use the [publishers tools](https://directory.app.net/broadcast/manage/). Either way, we are all setup to send a Broadcast. + +## Send a Broadcast + +A Broadcast is a message that is received as a push notification. To send a Broadcast we are going to publish a [Message](/docs/resources/message/) to a [Channel](/docs/resources/channel/). + +Continuing with our example of Mikhail Borscht Food Truck, lets send a broadcast to our customers. Say we just setup our truck at 5th and mission and we want to tell them where we are. + +Well, first we'll need to figure out what our subject should be. A subject is what a user will see in their push notification. It's kind of like the subject of an e-mail. It should give the user enough information so that they will know who its from and entice them to open the Broadcast. For our purposes that might be something like: + + Mikhail Borscht will be at 5th and Mission with 2 for 1 perogies till 2pm + +But, we can add more information to our Broadcast. We add a text field to our message that can be up to 2048 characters. In most cases that will be significantly more characters then we will need. We shouldn't count on people to read long messages, but some extra detail could be nice. Also, you don't need to include text at all. The only required part of a Broadcast is the subject. In the case of Mikhail Borscht we might want to include our specials. + + Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce. + +A well formed Broadcast will have at least one annotation of type `net.app.core.broadcast.message.metadata`, which will include our subject. Optionally you can set the text field of the message as well. Now that we know what our subject and text will be we can construct a message. + +Just like our channel we are going to build a message object then serialize it to JSON and post it to the API. The object will look like this. + +~~~ python +message = { + "annotations": [{ + "type": "net.app.core.broadcast.message.metadata", "value": { - "title": "Mikhail Borscht Truck Location Updates.", - "description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you." + "subject": "Mikhail Borscht will be at 5th and Mission with 2 for 1 perogies till 2pm" } - } + }], + "text": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce." +} +~~~ + +Before you send the Broadcast take a second to make sure all the information is correct. This is going to be sent as a push notification to people and that push notification won't be retractable. You can always delete the Broadcast, but that won't remove all traces of it. That being said, lets send Mikhail Borscht's customers a Broadcast. + +Just like building our channel we are going to use curl (remember to check out the libraries page for something language specific.) + +~~~ sh +curl -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" \ +-d '{"text": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce.", "annotations": [{"type": "net.app.core.broadcast.message.metadata", "value": {"subject": "Mikhail Borscht will be at 5th and Mission with 2 for 1 perogies till 2pm"}}]}' \ +https://alpha-api.app.net/stream/0/channels/33990/messages +~~~ + +We just sent our first broadcast. Anyone who was subscribed to our channel will now receive a push notification. This is what the message resource looks like. + +~~~ js +{ + "meta": { + "code": 200 + }, + "data": { + "id": "1982421", + "thread_id": "1982421", + "user": { + ... + }, + "num_replies": 0, + "entities": { + "links": [], + "hashtags": [], + "mentions": [] + }, + "text": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce.", + "created_at": "2013-11-18T17:55:00Z", + "channel_id": "33990", + "source": { + "client_id": "7pZRYcWwaxUJxw24XTHarUC7e676h8t5", + "name": "Sam Sharps App", + "link": "https://app.net/samsharp" + }, + "html": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce.", + "machine_only": false + } } ~~~ -Okay, now we are ready to create our broadcast channel. +So, in this guide we covered how to create a broadcast channel, and how to send a broadcast to all of your subscribers. + + + + + + + + + + + diff --git a/static/css/style.css b/static/css/style.css index 99a7166..5cf1023 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -83,19 +83,19 @@ body h1, body h2, body h3 { } body h1 { - font-size: 38.5px;; + font-size: 36px; } body h2 { - font-size: 31.5px; + font-size: 26px; } body h3 { - font-size: 24.5px; + font-size: 22px; } body h4 { - font-size: 17.5px; + font-size: 20px; } body h2, body h3, body h4, body h5 { @@ -104,6 +104,10 @@ body h2, body h3, body h4, body h5 { margin-bottom: .5em; } +p, div.layout-like-p { + line-height: 20px; + font-size: 14px; +} ul.nav-list ul.nav-list ul.nav-list li a { padding-left: 50px; @@ -158,10 +162,15 @@ html.breakpoint-tablet .nav-list { width: auto; } +pre { + border: 1px solid #aaa; +} + pre code { white-space: pre-wrap; } -pre code, pre {background-color:#073642;color:#93a1a1} + +pre code, pre {background-color:#073642;color:#93a1a1;} pre code .c{color:#586e75 !important;font-style:italic !important} pre code .cm{color:#586e75 !important;font-style:italic !important} pre code .cp{color:#586e75 !important;font-style:italic !important} From 16c603a87d3946c1287960d872119c5185056b11 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 20 Nov 2013 17:12:46 -0800 Subject: [PATCH 136/231] Copy changes from storus --- content/docs/guides/send-a-broadcast.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index cfea403..305b9f5 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -31,7 +31,7 @@ A good description might be: Now that we have decided on a title and description we can start constructing a channel object that we will send to the API to create a broadcast channel. -**You can create channels using the API, but it might be easier to create your channel using our [publisher tools](https://directory.app.net/broadcast/manage/) instead.** +**You can create channels using the API, but it might be easier to create your broadcast channel using our [publisher tools](https://directory.app.net/broadcast/manage/) instead.** It's a good idea to start creating a channel object in a way that you can easily serialize to a JSON string. In python that might be a dict, and in JavaScript that might be an object literal. Pick the one that is right for your language. From 4c1ea492e7c6bc49851cf51afa3ac1744f22a07e Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Thu, 21 Nov 2013 00:02:27 -0800 Subject: [PATCH 137/231] Most of the core API changes to be launched with Broadcasts --- content/docs/meta/annotations.md | 7 ++- content/docs/meta/entities.md | 25 +++++++- content/docs/resources/channel/index.md | 57 ++++++++++++++++--- content/docs/resources/channel/lifecycle.md | 31 +++++++++- content/docs/resources/channel/lookup.md | 38 +++++++++++++ .../docs/resources/channel/subscriptions.md | 8 ++- content/docs/resources/interaction/index.md | 9 +-- layouts/partials/endpoints/channel.md | 18 ++++++ lib/sample_objects.rb | 30 ++++++++++ 9 files changed, 206 insertions(+), 17 deletions(-) diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index 7f3cf17..b7291b3 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -96,7 +96,8 @@ All objects that support annotations (User, Post, Channel, Message, File) have a - A Post or Message can have multiple annotations of the same "type". - User and Channel annotations are mutable and can be updated at any time. - Because they are mutable, a User or Channel object can only have one annotation of each "type". -- User annotations are meant to provide more information about the user. **They are not meant to be an arbitrary data store for apps**. +- User annotations are meant to provide more information about the user. **They are not meant to be an arbitrary data store for apps**. +- Some annotations are read-only and will be ignored or rejected if you try to write to them. ### Creating, Updating and Deleting @@ -145,12 +146,14 @@ We currently define the following core annotations: | [Embedded Media](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) | net.app.core.oembed | Provides information for displaying an image, video, or other rich content. | | [oEmbed Metadata](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.metadata.md) | net.app.core.oembed.metadata | Provides information for generating an oEmbed representation of a file. | -We will be defining core annotations soon for the following types of data: +We have considered core annotations for the following types of data: * Long-form content * Attribution and source * Additional content license grants, where users can opt in to Creative Commons licensing, etc., if desired. +If you are interested in these ideas, please [open an issue](https://github.com/appdotnet/object-metadata/issues). + Developers are encouraged to create annotations for data not well represented here. If possible, care should be taken not to overlap with existing annotations. Annotations designed to address edge-cases in well-known annotations should include both the well-known annotation and only the augmented parts in the enhancing annotation. ### Annotation replacement values diff --git a/content/docs/meta/entities.md b/content/docs/meta/entities.md index ad50569..64c8299 100644 --- a/content/docs/meta/entities.md +++ b/content/docs/meta/entities.md @@ -204,9 +204,9 @@ Entities are automatically extracted from the post text but there are 2 cases wh ### Links with custom anchor text -If you'd like to provide a link without including the entire URL in your post text or user description, you can specify a custom link at Post creation time or User update time. **If you include a list of links in your Post — even an empty list — App.net by default will not extract any links on the server.** Mentions and hashtags will still be extracted. If you want App.net to still extract links, you can pass the `parse_links: true` option to App.net. User provided links will take precedence over any links, mentions, or hashtags that App.net detects. However, a user provided link can not partially overlap with a mention or hashtag. +If you'd like to provide a link without including the entire URL in your post text or user description, you can specify a custom link at Post creation time or User update time. **If you include a list of links in your Post — even an empty list — App.net by default will not extract any links on the server.** Mentions and hashtags will still be extracted. If you want App.net to still extract links, you can pass the `parse_links: true` option to App.net. User provided links will take precedence over any links, mentions, or hashtags that App.net detects. However, a user provided link cannot partially overlap with a mention or hashtag. -As an example, the following JSON will create a post to 2 links 1) the parsed link to App.net and 2) the user provided link to the App.net blog: +As an example, the following JSON will create a post with 2 links 1) the parsed link to App.net and 2) the user provided link to the App.net blog: ~~~js { @@ -224,6 +224,27 @@ As an example, the following JSON will create a post to 2 links 1) the parsed li } ~~~ +Many apps like to use [inline Markdown link syntax](http://daringfireball.net/projects/markdown/syntax#link) to create user provided links. To make that easier, App.net can process the markdown links server side to populate the `entities`. Essentially, App.net will parse the `text` value for Markdown links overwriting any `links` you provided. The same rules for `parse_links` still apply when using Markdown. + +As an example, the following JSON will create a post with 2 links 1) the parsed link to App.net and 2) the user provided (via Markdown) link to the App.net blog. The link provided in `entities.links` is discarded and replaced with the Markdown links becase `parse_markdown_links` is true. + +~~~js +{ + "text": "The official App.net [blog](http://blog.app.net) is here", + "entities": { + "links": [ + { + "pos": 0, + "len": 3, + "url": "http://app.net/mthurman" + } + ], + "parse_links": true, + "parse_markdown_links": true + } +} +~~~ + To prevent phishing, any link where the anchor text differs from the destination domain will be followed by the domain of the link target. These extra characters added by App.net to the `text` field will not count against the 256 character Post limit. In this case, App.net will also add the [`amended_len`](#links) field that includes the length of the complete entity and added anti-phishing text. This will make it easier for apps to customize how the anti-phishing protection looks in their apps. **When rendering links in your app, you must show users an indication of where they will end up.** The ```text``` attribute of a link should be omitted as it will always be filled in from the post text. diff --git a/content/docs/resources/channel/index.md b/content/docs/resources/channel/index.md index c8f629c..51827d7 100644 --- a/content/docs/resources/channel/index.md +++ b/content/docs/resources/channel/index.md @@ -14,10 +14,19 @@ A Channel is a user created stream of Messages. It controls access to the messag ~~~ js { "counts": { - "messages": 42 + "messages": 42, + "subscribers": 43 }, "has_unread": true, "id": "1", + "is_inactive": false + "editors": { + "any_user": false, + "immutable": false, + "public": false, + "user_ids": [], + "you": true + }, "owner": { ... }, @@ -78,6 +87,11 @@ A Channel is a user created stream of Messages. It controls access to the messag integer The number of Messages in the channel. + + subscribers + integer + The number of Users subscribed to this channel. This field is only shown to channel editors. + @@ -106,6 +120,11 @@ A Channel is a user created stream of Messages. It controls access to the messag ACL object The access control list that describes who can read this Channel and its Messages. + + editors + ACL object + The access control list that describes who can edit this Channel object. + writers ACL object @@ -124,7 +143,7 @@ A Channel is a user created stream of Messages. It controls access to the messag you_can_edit boolean - Are you allowed to edit the Channel. + Are you allowed to edit the Channel. This is deprecated. editors.you should be used instead. has_unread @@ -152,6 +171,13 @@ A Channel is a user created stream of Messages. It controls access to the messag ## ACL ~~~ js +"editors": { + "any_user": false, + "immutable": false, + "public": false, + "user_ids": [], + "you": true +}, "readers": { "any_user": false, "immutable": false, @@ -172,7 +198,7 @@ A Channel is a user created stream of Messages. It controls access to the messag } ~~~ -Access control lists (ACLs) specify who can read and who can write Messages in a Channel. In our permissions model, writing implies reading. Note that `any_user`, `public`, and non-empty `user_ids` are all mutually exclusive (only one of those can be true at a time). Also, the creator of a Channel always has write access and will not be specified in the `user_ids` list. For some Channel types (like `net.app.core.pm`), the ACLs will be sanitized to make sure they fit a specific schema. Please see the [Messaging overview](/docs/basics/messaging/) for more information. +Access control lists (ACLs) specify who can edit a channel and read or write Messages to a Channel. In our permissions model, editing implies writings and writing implies reading. Note that `any_user`, `public`, and non-empty `user_ids` are all mutually exclusive (only one of those can be true at a time). Also, the creator of a Channel always has edit access and will not be specified in the `user_ids` list. For some Channel types (like `net.app.core.pm`), the ACLs will be sanitized to make sure they fit a specific schema. Please see the [Messaging overview](/docs/basics/messaging/) for more information. `editors` can edit the channel ACLs, annotations, write messages and perform any action against a channel except for marking it as inactive. Only an owner can mark a channel as inactive. ### ACL Fields @@ -188,7 +214,7 @@ Access control lists (ACLs) specify who can read and who can write User read/write to this Channel? If true, public will be false and user_ids will be empty. + Can any logged in User read/write to this Channel? This will always be false for the editors ACL. If true, public will be false and user_ids will be empty. immutable @@ -198,12 +224,12 @@ Access control lists (ACLs) specify who can read and who can write Users), read this channel. This will always be false for the writers ACL. If true, any_user will be false and user_ids will be empty. + Can anyone (including not logged in Users), read this channel. This will always be false for the writers and editors ACLs. If true, any_user will be false and user_ids will be empty. user_ids list - A list of strings specifying the ids of Users who can read/write to this Channel. If non-empty, any_user and public will be false. This list can contain at most 200 User ids. + A list of strings specifying the ids of Users who can read/write to this Channel. If non-empty, any_user and public will be false. This list can contain at most 200 User ids except for Broadcast channels which allow an unlimited number of readers. you @@ -223,7 +249,7 @@ For more information on Annotations in general, see the [Annotations](/docs/meta A Channel's `type` can be used to identify the behavior of a Channel. Channel types are specified by the application creating the Channel and should have corresponding entries in the [channel-types directory](https://github.com/appdotnet/object-metadata/tree/master/channel-types) describing their behavior. -There is currently one core Channel type: +There is currently 2 core Channel types: #### Private Message @@ -238,6 +264,17 @@ This Channel type is for private messages between 2 or more people. As a core Ch You can create arbitrary Channel types which do not have these restrictions (but are able to maintain the same level of privacy.) +#### Broadcast Channel + +> [net.app.core.broadcast](https://github.com/appdotnet/object-metadata/blob/master/channel-types/net.app.core.broadcast.md) + +This Channel type is for broadcasting very occasional, high value information groups of people. + +- Broadcast channels must not have multiple writers. If you'd like multiple people to be able to publish to a Broadcast channel, you must make them all editors. +- Broadcast channels can have an unlimited number of readers explicitly specified. +- You *cannot* auto-subscribe anyone to Broadcast channels. They are opt-in. + + ## General Parameters Where noted, Channel endpoints respond to the following query string parameters: @@ -294,6 +331,12 @@ Where noted, Channel endpoints respond to the following query string parameters: integer (0 or 1) Should Message annotations be included in the response objects? Defaults to false. + + include_inactive + Optional + integer (0 or 1) + Should inactive channels be included? Defaults to false. + diff --git a/content/docs/resources/channel/lifecycle.md b/content/docs/resources/channel/lifecycle.md index 97ffe0e..d88bed6 100644 --- a/content/docs/resources/channel/lifecycle.md +++ b/content/docs/resources/channel/lifecycle.md @@ -11,7 +11,7 @@ title: "Channel Lifecycle" Create a new [Channel](/docs/resources/channel/). -Send a JSON document that matches the [Channel schema](/docs/resources/channel/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```readers```, ```writers```, ```annotations```, and ```type```. +Send a JSON document that matches the [Channel schema](/docs/resources/channel/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```readers```, ```writers```, ```annotations```, and ```type```. The owner will be auto-subscribed to this channel. ### Creating a PM Channel @@ -127,3 +127,32 @@ This endpoint currently works identically for the `PUT` and `PATCH` HTTP methods } } ~~~ + + +## Deactivate a Channel + +Mark a channel as inactive. This **does not** delete the contents of the Channel. It prevents new messages from being added to the channel and unsubscribes all users from the Channel. This channel will be hidden unless it is explicitly requested by id or the `include_inactive=1` parameter is used. This is irreversible. + +The current user must be the same user who created the Channel. *Editors cannot delete a channel* + +*net.app.core.pm* channels cannot be marked as inactive. + +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* + +<%= general_params_note_for "channel" %> + +<%= endpoint "DELETE", "channel/[channel_id]", "User" %> + +<%= url_params [ + ["channel_id", "The id of the Channel to delete."] +]%> + +### Example + +> DELETE https://alpha-api.app.net/stream/0/channel/1 + +<%= response(:channel) do |h| + h["data"]["is_inactive"] = true + h["data"]["counts"]["subscribers"] = 0 + h["you_subscribed"] = false +end %> diff --git a/content/docs/resources/channel/lookup.md b/content/docs/resources/channel/lookup.md index 2271024..64aac02 100644 --- a/content/docs/resources/channel/lookup.md +++ b/content/docs/resources/channel/lookup.md @@ -221,3 +221,41 @@ Returns the current number of `net.app.core.pm` Channels where `has_unread: true } } ~~~ + + +## Retrieve number of unread Broadcast Channels +Returns the current number of `net.app.core.broadcast` Channels where `has_unread: true` for the current user. + +<%= endpoint "GET", "users/me/channels/broadcast/num_unread", "User", "messages"%> + +#### Example + +> GET https://alpha-api.app.net/stream/0/users/me/channels/broadcast/num_unread + +~~~ js +{ + "data": 3, + "meta": { + "code": 200 + } +} +~~~ + + +## Mark all Broadcast Channels as read +Mark all `net.app.core.broadcast` Channels as read for the current user. + +<%= endpoint "DELETE", "users/me/channels/broadcast/num_unread", "User", "messages"%> + +#### Example + +> DELETE https://alpha-api.app.net/stream/0/users/me/channels/broadcast/num_unread + +~~~ js +{ + "data": 0, + "meta": { + "code": 200 + } +} +~~~ diff --git a/content/docs/resources/channel/subscriptions.md b/content/docs/resources/channel/subscriptions.md index 1aa7c26..b2b7fbe 100644 --- a/content/docs/resources/channel/subscriptions.md +++ b/content/docs/resources/channel/subscriptions.md @@ -11,6 +11,8 @@ title: "Channel Subscriptions" Retrieve an "inbox" of the channels the user is currently subscribed to. This stream is ordered like an inbox with the stream containing the most recent post first. +The `meta` response will contain unread counts for common channel types. + <%= general_params_note_for "channel" %> <%= pagination_note %> @@ -59,7 +61,11 @@ Retrieve an "inbox" of the channels the user is currently subscribed to. This st "code": 200, "max_id": 146, "min_id": 123, - "more": true + "more": true, + "unread_counts": { + "net.app.core.pm": 5, + "net.app.core.broadcast": 3 + } } } ~~~ diff --git a/content/docs/resources/interaction/index.md b/content/docs/resources/interaction/index.md index 86ac28f..76a30e9 100644 --- a/content/docs/resources/interaction/index.md +++ b/content/docs/resources/interaction/index.md @@ -7,9 +7,9 @@ title: "Interactions" * TOC {:toc} -Interactions are objects that represent users taking certain actions on App.net. Currently an Interaction is created when a User replies to, reposts, or stars a Post, or follows another User. Interactions are structured to form a sentence like: User X took action Y on object Z. If multiple users take the same action (e.g. multiple users reply to one post) within a set time window those events will be combined into a single Interaction. +Interactions are objects that represent users taking certain actions on App.net. Interactions are structured to form a sentence like: User X took action Y on object Z. If multiple users take the same action (e.g. multiple users reply to one post) within a set time window those events will be combined into a single Interaction. -> Note: currently only one User or Post will be returned in the ```objects``` list of an Interaction but future actions may target multiple objects per Interaction. +> Note: the `objects` list of an Interaction will vary based on the `action` (Example) @dalton and @berg reposted post 1: @@ -66,7 +66,7 @@ Interactions are objects that represent users taking certain actions on App.net. action string - What users did. Currently one of follow, reply, repost, or star + What users did. Currently one of follow, reply, repost, star, welcome, broadcast_create, broadcast_subscribe, or broadcast_unsubscribe. event_date @@ -76,7 +76,7 @@ Interactions are objects that represent users taking certain actions on App.net. objects list - users took action on. These objects will be Users if action=follow + users took action on. These objects will be Users if action=follow. For star, repost, reply these objects will be Posts. For broadcast_create, broadcast_subscribe, broadcast_subscribe these will be channels. For welcome this will be empty. users @@ -97,6 +97,7 @@ List all the [Interactions](/docs/resources/interaction/) other users have had w > Note: although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/docs/resources/app-stream/) to monitor the global feed for relevant activity. +This endpoint accepts the `interaction_actions` as a query string parameter whose value is a comma separated list of actions you're interested in. For instance, if you're only interested in repost and follow interactions you could request `stream/0/users/me/interactions?interaction_actions=repost,follow`. <%= endpoint "GET", "users/me/interactions", "User" %> diff --git a/layouts/partials/endpoints/channel.md b/layouts/partials/endpoints/channel.md index f6129b3..e4f6e97 100644 --- a/layouts/partials/endpoints/channel.md +++ b/layouts/partials/endpoints/channel.md @@ -44,12 +44,30 @@ /stream/0/users/me/channels/pm/num_unread User + + Retrieve number of unread Broadcast Channels + GET + /stream/0/users/me/channels/broadcast/num_unread + User + + + Mark all Broadcast Channels as read + DELETE + /stream/0/users/me/channels/broadcast/num_unread + User + Update a Channel PUT /stream/0/channels/[channel_id] User + + Deactivate a Channel + DELETE + /stream/0/channels/[channel_id] + User + Subscribe to a Channel POST diff --git a/lib/sample_objects.rb b/lib/sample_objects.rb index 82d9be7..484f036 100644 --- a/lib/sample_objects.rb +++ b/lib/sample_objects.rb @@ -227,6 +227,36 @@ def paginated_response(key, &block) "annotation_max_bytes" => 8192 } } + + CHANNEL = { + "counts" => { + "messages" => 42, + "subscribers" => 43 + }, + "has_unread" => false, + "id" => "1", + "owner" => "...user object...", # TODO render this as a user placholder somehow + "is_inactive" => false, + "readers" => { + "any_user" => false, + "immutable" => false, + "public" => true, + "user_ids" => [], + "you" => true + }, + "type" => "com.example.channel", + "writers" => { + "any_user" => false, + "immutable" => false, + "public" => false, + "user_ids" => [ + "1" + ], + "you" => true + }, + "you_can_edit" => true, + "you_subscribed" => true + } end include Resources::Helpers From 013ae3c937bbe796aecd7248a577413e4dfb9442 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 21 Nov 2013 11:20:35 -0800 Subject: [PATCH 138/231] Link up new guides --- layouts/default.html | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/layouts/default.html b/layouts/default.html index a43711e..79476f6 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -53,6 +53,12 @@
  • Messaging API
    • +
  • Guides
    • + +
  • External Resources
    • My Apps
      • From 865f72b1d7a343779f49e17ae5305e8882b6ed0e Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Thu, 21 Nov 2013 12:24:03 -0800 Subject: [PATCH 139/231] Updating image --- content/docs/guides/create-an-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/guides/create-an-app.md b/content/docs/guides/create-an-app.md index 2e66413..3307c87 100644 --- a/content/docs/guides/create-an-app.md +++ b/content/docs/guides/create-an-app.md @@ -53,7 +53,7 @@ To see a list of your current apps visit [account.app.net/settings/developer/.]( Find the app you would like to generate an access token for and click on the name. You should now see your app detail page. -![Generate a token](https://files.app.net/01q9srKw.png) +![Generate a token](https://files.app.net/0q1t3Zt2.png) From this screen, if you look at the second block you will see a link: 'Generate a user token for yourself'. Click on that link, and you will see a page like this. From ebc95a3fed954d3072aa892d25e5ec5c4090cf99 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Fri, 22 Nov 2013 13:52:44 -0800 Subject: [PATCH 140/231] Update front page of docs --- content/index.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/index.md b/content/index.md index c7224f2..0abfe84 100644 --- a/content/index.md +++ b/content/index.md @@ -16,12 +16,11 @@ To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adna {::options parse_block_html="true" /}
      +* (11/21/2013) **Introducing App.net Broadcast** - check out the [Send a Broadcast](/docs/guides/send-a-broadcast/) guide. * (7/25/2013) **Introducing the Search API** — check out the documentation for [Post Search](/docs/resources/post/search/). * (6/17/2013) **Introducing the User Stream API** — check out the documentation for [User Streams](/docs/resources/user-stream/). * (2/5/2013) **Introducing the Place API** — check out the documentation for [Places](/docs/resources/place/). * (1/28/2013) **Introducing the File API** — check out the documentation for [Files](/docs/resources/file/). -* (12/13/2012) **Introducing the Messaging API** — check out the documentation for [Channels](/docs/resources/channel/) and [Messages](/docs/resources/message/) and the [App.net Messaging overview](/docs/basics/messaging/). -* (12/13/2012) **Documentation has a new look and organization!**
      ### Getting help and providing feedback From def96546eb2a3aa14eff3e56e49ec0399c6bd021 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Fri, 22 Nov 2013 13:55:57 -0800 Subject: [PATCH 141/231] More updates --- content/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/index.md b/content/index.md index 0abfe84..25d63db 100644 --- a/content/index.md +++ b/content/index.md @@ -12,7 +12,7 @@ This page is your starting point to getting familiar with the App.net developer ### Tracking news and announcements -To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adnapi). You may also want to subscribe to the [App.net blog](http://blog.app.net/) for general news and the [developer blog](http://devblog.app.net/) for developer related news. +To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adnapi). You may also want to subscribe to the [App.net blog](https://broadcast.app.net/26283/appnet-blog/) for general news and [App.net API Updates](https://broadcast.app.net/24368/appnet-api-updates/) for developer related news. {::options parse_block_html="true" /}
      From eb2247d56e0be8aaf34fe66ca4f19baa8d832ee9 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Fri, 22 Nov 2013 16:10:31 -0800 Subject: [PATCH 142/231] update links in the dos --- content/docs/guides/send-a-broadcast.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index 305b9f5..92d7262 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -10,7 +10,7 @@ To start sending broadcasts from the API you will need an access token. Date: Mon, 9 Dec 2013 16:18:55 +0000 Subject: [PATCH 143/231] Fix apostrophes in send-a-broadcast guide. Corrected various apostrophe-related issues (either missing or there when they shouldn't be). --- content/docs/guides/send-a-broadcast.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index 305b9f5..52a44fa 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -8,7 +8,7 @@ title: "Send A Broadcast From The API" To start sending broadcasts from the API you will need an access token. Read our guide an creating an app to get an access token.
      -Broadcast channels are mean't for low-volume high-value updates that users are interested in. Because broadcasts are built on top of our existing [Channels](/docs/resources/channel/), and [Messages](/docs/resources/message/) API there isn't much new stuff you need to know. In this guide we will go over the specifics of creating a Broadcast Channel and a Broadcast. +Broadcast channels are meant for low-volume high-value updates that users are interested in. Because broadcasts are built on top of our existing [Channels](/docs/resources/channel/), and [Messages](/docs/resources/message/) API there isn't much new stuff you need to know. In this guide we will go over the specifics of creating a Broadcast Channel and a Broadcast. While you can do all of this using our API you don't have to. We have [publishers tools](https://directory.app.net/broadcast/manage/) to help you quickly get started. @@ -19,7 +19,7 @@ While you can do all of this using our API you don't have to. We have [publisher Before you create your channel you should come up with a compelling title and description for your channel. Users will use this information to decide if they want to subscribe to your channel. Take an extra moment before you dive in. Also, keep in mind that users will be able to see how often your Broadcast Channel updates and may choose to not subscribe to high volume channels. -For this example, lets say we are going to create a Broadcast Channel for a food truck called Mikhail Borscht. We want to send a Broadcast every time we setup our truck. Using Broadcasts we will immediately be able to inform our customers of our location, our specials for the day, or anything that is of a timely nature. +For this example, let's say we are going to create a Broadcast Channel for a food truck called Mikhail Borscht. We want to send a Broadcast every time we setup our truck. Using Broadcasts we will immediately be able to inform our customers of our location, our specials for the day, or anything that is of a timely nature. We might title this channel: @@ -54,7 +54,7 @@ We set our annotation to a type of `net.app.core.broadcast.metadata`. Then we se But, we aren't done creating our channel object. Next, we need to decide who can read our broadcasts, and who can send send broadcasts. -To do that we are going to add two [ACL's](/docs/resources/channel/#acl) to our channel object. A readers ACL, and an editors ACL. +To do that we are going to add two [ACLs](/docs/resources/channel/#acl) to our channel object. A readers ACL, and an editors ACL. This channel will be public. Public means anyone, even people who aren't App.net users, will be able to read from this Broadcast Channel. Also, since it won't make sense for the public nature of this channel to change and we don't want anyone to accidentally mark it as private, we are going to make this channel's readers ACL as immutable. @@ -157,7 +157,7 @@ A Broadcast is a message that is received as a push notification. To send a Broa Continuing with our example of Mikhail Borscht Food Truck, lets send a broadcast to our customers. Say we just setup our truck at 5th and mission and we want to tell them where we are. -Well, first we'll need to figure out what our subject should be. A subject is what a user will see in their push notification. It's kind of like the subject of an e-mail. It should give the user enough information so that they will know who its from and entice them to open the Broadcast. For our purposes that might be something like: +Well, first we'll need to figure out what our subject should be. A subject is what a user will see in their push notification. It's kind of like the subject of an e-mail. It should give the user enough information so that they will know who it's from and entice them to open the Broadcast. For our purposes that might be something like: Mikhail Borscht will be at 5th and Mission with 2 for 1 perogies till 2pm @@ -181,7 +181,7 @@ message = { } ~~~ -Before you send the Broadcast take a second to make sure all the information is correct. This is going to be sent as a push notification to people and that push notification won't be retractable. You can always delete the Broadcast, but that won't remove all traces of it. That being said, lets send Mikhail Borscht's customers a Broadcast. +Before you send the Broadcast take a second to make sure all the information is correct. This is going to be sent as a push notification to people and that push notification won't be retractable. You can always delete the Broadcast, but that won't remove all traces of it. That being said, let's send Mikhail Borscht's customers a Broadcast. Just like building our channel we are going to use curl (remember to check out the libraries page for something language specific.) From 5eaf4ca77fe9dd1904c541d0252b93e443a5cd54 Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Thu, 12 Dec 2013 19:12:26 -0800 Subject: [PATCH 144/231] Revs to the send-a-broadcast guide --- content/docs/guides/send-a-broadcast.md | 342 +++++++++++------------- 1 file changed, 152 insertions(+), 190 deletions(-) diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index 92d7262..700c32d 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -1,245 +1,207 @@ --- -title: "Send A Broadcast From The API" +title: "Broadcasts and the API" --- -# Send a broadcast using the API +# Publishing Broadcasts via the API
      -To start sending broadcasts from the API you will need an access token. Read our guide an creating an app to get an access token. +To start sending broadcasts directly from the API, you'll need an access token. If you're not familiar with how to get an access token, check out our guide on creating an app.
      -Broadcast channels are mean't for low-volume high-value updates that users are interested in. Because broadcasts are built on top of our existing [Channels](/docs/resources/channel/), and [Messages](/docs/resources/message/) API there isn't much new stuff you need to know. In this guide we will go over the specifics of creating a Broadcast Channel and a Broadcast. +Broadcast Channels are designed to carry low-volume, high-value updates of interest to users. We call the actual updates themselves Broadcast Messages (or sometimes just "broadcasts"). Because broadcasts are built on top of the existing App.net [Channel](/docs/resources/channel/) and [Message](/docs/resources/message/) APIs, it's helpful to be familiar with them, but for simple tasks, there's not much you need to know. -While you can do all of this using our API you don't have to. We have [publishers tools](https://broadcast.app.net/manage/) to help you quickly get started. +Just a reminder: while you can do all of this using our API, you don't have to. We have [tools for publishers](https://broadcast.app.net/manage/) to help you quickly get started pulling content in from elsewhere on the web, and you can send them manually via the web or the App.net iOS and Android apps. To get started, **we recommend that you create and set up your broadcast channel with [our web publisher tools](https://broadcast.app.net/manage/)** and only use the API to send broadcasts via the channel you created. * TOC {:toc} -## Create a Broadcast Channel - -Before you create your channel you should come up with a compelling title and description for your channel. Users will use this information to decide if they want to subscribe to your channel. Take an extra moment before you dive in. Also, keep in mind that users will be able to see how often your Broadcast Channel updates and may choose to not subscribe to high volume channels. - -For this example, lets say we are going to create a Broadcast Channel for a food truck called Mikhail Borscht. We want to send a Broadcast every time we setup our truck. Using Broadcasts we will immediately be able to inform our customers of our location, our specials for the day, or anything that is of a timely nature. - -We might title this channel: - - Mikhail Borscht Truck Location Updates +## Send a Broadcast -A good description might be: +There are a number of parts to each broadcast message. To illustrate, here's a screenshot of a broadcast in the App.net iOS app: - Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you and what our specials for the day will be. +![Anatomy of a broadcast](https://files.app.net/rw8fPgku.png) -Now that we have decided on a title and description we can start constructing a channel object that we will send to the API to create a broadcast channel. +The important parts are the **Headline**, **Photo**, **Text** and **Read More Link**. Everything but the headline is optional, but we recommend that your broadcasts contain a compelling image and some context through a summary text body and a link to content. -**You can create channels using the API, but it might be easier to create your broadcast channel using our [publisher tools](https://broadcast.app.net/manage/) instead.** +The easiest way to send a broadcast with the API is via the [ADNPy](http://adnpy.readthedocs.org) Python module or the [adn](https://github.com/adn-rb/adn) Ruby gem. You can also use the HTTP API with your own client, if you'd like. -It's a good idea to start creating a channel object in a way that you can easily serialize to a JSON string. In python that might be a dict, and in JavaScript that might be an object literal. Pick the one that is right for your language. +Starting with Python, here's an example of using the ADNPy `BroadcastMessageBuilder` recipe. If you're interested in the specific API calls the library is making behind the scenes, [look at the source](https://github.com/appdotnet/ADNpy/blob/master/adnpy/recipes/broadcast.py). -The first part of our channel definition will be putting our title and description into an appropriate [annotation](/docs/meta/annotations/). Also, Broadcast Channels are a special type of of Channel, they have the type `net.app.core.broadcast` we will be adding that to our channel object as well. +Once you've installed the ADNPy library, it's as simple as: ~~~ python -channel = { - "type": "net.app.core.broadcast", - "annotations": [{ - "type": "net.app.core.broadcast.metadata", - "value": { - "title": "Mikhail Borscht Truck Location Updates.", - "description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you." - } - }] -} +import adnpy + +# Set the default access token for API calls. +adnpy.api.add_authorization_token('your access token here') + +# Send a broadcast with the BroadcastMessageBuilder recipe. +builder = adnpy.recipes.BroadcastMessageBuilder(adnpy.api) +builder.channel_id = 24204 # Get this channel ID from the web publisher tools +builder.headline = 'Hello World!' +builder.text = 'Sending this from [ADNPy](https://github.com/appdotnet/ADNPy) was easy!' +builder.parse_markdown_links = True +builder.read_more_link = 'http://adnpy.readthedocs.org/' +builder.send() ~~~ -We set our annotation to a type of `net.app.core.broadcast.metadata`. Then we set the value of the annotation to our title and description. Now anyone that can access the API can also know what this broadcast channel is about. - -But, we aren't done creating our channel object. Next, we need to decide who can read our broadcasts, and who can send send broadcasts. - -To do that we are going to add two [ACL's](/docs/resources/channel/#acl) to our channel object. A readers ACL, and an editors ACL. - -This channel will be public. Public means anyone, even people who aren't App.net users, will be able to read from this Broadcast Channel. Also, since it won't make sense for the public nature of this channel to change and we don't want anyone to accidentally mark it as private, we are going to make this channel's readers ACL as immutable. - -Marking an ACL immutable means we won't be able to change it after we create it. Once we have added our readers ACL our channel object should look like this. +You can easily attach a photo: ~~~ python -channel = { - "type": "net.app.core.broadcast", - "readers": { - "public": True, - "immutable": True, - }, - "annotations": [{ - ... - }] -} +builder.photo = '/home/paul/celeryman.gif' ~~~ -We need to add one more ACL to determine who can edit this channel. Being able to edit this channel means they can change the channel metadata and send broadcasts. We are only going mark two users as editors, but we are going to make the editors ACL mutable so we can change this in the future. Our updated channel object should now look something like this. +If you want to send the equivalent broadcast from the API without using a library, use this curl command: -~~~ python -channel = { - "type": "net.app.core.broadcast", - "readers": { - ... - }, - "editors": { - "user_ids": ['@samsharp', '@sfborscht'], - "immutable": False, - }, - "annotations": [{ - ... - }] -} +~~~ sh +curl -X POST -H "Authorization: Bearer " \ + -H "X-adn-pretty-json: 1" -H "Content-Type: application/json" \ + --data-ascii '{ + "text": "Here is a [link](http://www.google.com) for my text body.", + "annotations": [ + { + "value": { + "subject": "Hello world!" + }, + "type": "net.app.core.broadcast.message.metadata" + }, + { + "value": { + "canonical_url": "http://www.example.com/" + }, + "type": "net.app.core.crosspost" + } + ], + "entities": { + "parse_markdown_links": true, + "parse_links": true + } + }' \ + \ + 'https://alpha-api.app.net/stream/0/channels?include_annotations=1' ~~~ -We are now ready to create our broadcast channel. For the purposes of this demo we are going to use curl, but you should checkout the client libraries page and use a language specific library. +## Create a Broadcast Channel -~~~ sh -curl -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" \ --d '{"annotations": [{"type": "net.app.core.broadcast.metadata", "value": {"description": "Mikhail Borscht is the premier borscht truck in the SF soma neighborhood. Subscribe to our broadcasts to know when we are near you.", "title": "Mikhail Borscht Truck Location Updates."}}], "type": "net.app.core.broadcast", "editors": {"user_ids": ["@samsharp", "@sfborscht"], "immutable": false}, "readers": {"public": true, "immutable": true}}' \ -https://alpha-api.app.net/stream/0/channels -~~~ +You can create broadcast channels with the API as well. + +Broadcast channels are created like any other channel, with a specific type value (`net.app.core.broadcast`) and a few special annotations. For information on creating channels, see the [Channel lifecycle documentation](/docs/resources/channel/lifecycle/). Broadcast channels fully support [ACLs](/docs/resources/channel/) for private applications. -We will get back our channel resource. You will see that a bunch of information has been added into our channel. Our new channel also has an `id`. We can use that to address this channel in the future. +Here is an example channel body, set to be public, with multiple editors, which you can POST to us: ~~~ js { - "meta": { - "code": 200 - }, - "data": { - "id": "33990", "type": "net.app.core.broadcast", - "counts": { - "subscribers": 1, - "messages": 0 - }, - "owner": { - "name": "Sam Sharp", - ... - }, - "is_inactive": false, "readers": { - "immutable": true, - "you": true, - "any_user": false, - "user_ids": [], - "public": true + "public": true }, - "you_muted": false, - "you_can_edit": true, - "has_unread": false, "editors": { - "immutable": false, - "you": true, - "any_user": false, - "user_ids": [ - "190195" - ], - "public": false + "user_ids": ["@samsharp", "@sfborscht"], }, - "writers": { - "immutable": false, - "you": true, - "any_user": false, - "user_ids": [], - "public": false - }, - "you_subscribed": true - } -} -~~~ - -We have now created a channel. We can continue to administer this channel via API, or we could use the [publishers tools](https://broadcast.app.net/manage/). Either way, we are all setup to send a Broadcast. - -## Send a Broadcast - -A Broadcast is a message that is received as a push notification. To send a Broadcast we are going to publish a [Message](/docs/resources/message/) to a [Channel](/docs/resources/channel/). - -Continuing with our example of Mikhail Borscht Food Truck, lets send a broadcast to our customers. Say we just setup our truck at 5th and mission and we want to tell them where we are. - -Well, first we'll need to figure out what our subject should be. A subject is what a user will see in their push notification. It's kind of like the subject of an e-mail. It should give the user enough information so that they will know who its from and entice them to open the Broadcast. For our purposes that might be something like: - - Mikhail Borscht will be at 5th and Mission with 2 for 1 perogies till 2pm - -But, we can add more information to our Broadcast. We add a text field to our message that can be up to 2048 characters. In most cases that will be significantly more characters then we will need. We shouldn't count on people to read long messages, but some extra detail could be nice. Also, you don't need to include text at all. The only required part of a Broadcast is the subject. In the case of Mikhail Borscht we might want to include our specials. - - Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce. - -A well formed Broadcast will have at least one annotation of type `net.app.core.broadcast.message.metadata`, which will include our subject. Optionally you can set the text field of the message as well. Now that we know what our subject and text will be we can construct a message. - -Just like our channel we are going to build a message object then serialize it to JSON and post it to the API. The object will look like this. - -~~~ python -message = { "annotations": [{ - "type": "net.app.core.broadcast.message.metadata", + "type": "net.app.core.broadcast.metadata", "value": { - "subject": "Mikhail Borscht will be at 5th and Mission with 2 for 1 perogies till 2pm" + "title": "SF Borscht Truck Updates", + "description": "Get a notification when the SF Borscht Food Truck will be on the streets!" } - }], - "text": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce." + }] } ~~~ -Before you send the Broadcast take a second to make sure all the information is correct. This is going to be sent as a push notification to people and that push notification won't be retractable. You can always delete the Broadcast, but that won't remove all traces of it. That being said, lets send Mikhail Borscht's customers a Broadcast. - -Just like building our channel we are going to use curl (remember to check out the libraries page for something language specific.) +Here's a sample curl command that'll create a channel: ~~~ sh -curl -X POST -H "Authorization: Bearer " -H "Content-Type: application/json" \ --d '{"text": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce.", "annotations": [{"type": "net.app.core.broadcast.message.metadata", "value": {"subject": "Mikhail Borscht will be at 5th and Mission with 2 for 1 perogies till 2pm"}}]}' \ -https://alpha-api.app.net/stream/0/channels/33990/messages +curl -X POST -H "Authorization: Bearer " \ + -H "X-adn-pretty-json: 1" -H "Content-Type: application/json" \ + --data-ascii '{ + "type": "net.app.core.broadcast", + "readers": { + "public": true + }, + "editors": { + "user_ids": ["@samsharp", "@sfborscht"] + }, + "annotations": [{ + "type": "net.app.core.broadcast.metadata", + "value": { + "title": "SF Borscht Truck Updates", + "description": "Get a notification when the SF Borscht Food Truck will be on the streets!" + } + }] + }' \ + \ + 'https://alpha-api.app.net/stream/0/channels?include_annotations=1' ~~~ -We just sent our first broadcast. Anyone who was subscribed to our channel will now receive a push notification. This is what the message resource looks like. +This will return a fully-populated channel resource, including the `id` of the channel, a few auto-generated annotations, and the `fallback_url`, which is the short URL for the channel's detail page. ~~~ js { - "meta": { - "code": 200 - }, - "data": { - "id": "1982421", - "thread_id": "1982421", - "user": { - ... - }, - "num_replies": 0, - "entities": { - "links": [], - "hashtags": [], - "mentions": [] + "data": { + "annotations": [ + { + "type": "net.app.core.broadcast.metadata", + "value": { + "description": "Get a notification when the SF Borscht Food Truck will be on the streets!", + "tags": [], + "title": "SF Borscht Truck Updates" + } + }, + { + "type": "net.app.core.broadcast.freq", + "value": { + "avg_freq": "less than 1 per week", + "intensity": 0.1 + } + }, + { + "type": "net.app.core.fallback_url", + "value": { + "url": "https://app.net/c/2rds" + } + } + ], + "counts": { + "messages": 0, + "subscribers": 1 + }, + "editors": { + "any_user": false, + "immutable": false, + "public": false, + "user_ids": [ + "190151", + "190195" + ], + "you": true + }, + "has_unread": false, + "id": "37332", + "is_inactive": false, + "owner": { + ... + }, + "readers": { + "any_user": false, + "immutable": false, + "public": true, + "user_ids": [], + "you": true + }, + "type": "net.app.core.broadcast", + "writers": { + "any_user": false, + "immutable": false, + "public": false, + "user_ids": [], + "you": true + }, + "you_can_edit": true, + "you_muted": false, + "you_subscribed": true }, - "text": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce.", - "created_at": "2013-11-18T17:55:00Z", - "channel_id": "33990", - "source": { - "client_id": "7pZRYcWwaxUJxw24XTHarUC7e676h8t5", - "name": "Sam Sharps App", - "link": "https://app.net/samsharp" - }, - "html": "Today the truck will be featuring a beet and goat cheese salad with candied walnuts. Also, we will be featuring beet chips made from fresh Sonoma produce.", - "machine_only": false - } + "meta": { + "code": 200 + } } ~~~ - -So, in this guide we covered how to create a broadcast channel, and how to send a broadcast to all of your subscribers. - - - - - - - - - - - - - - - - - - From 7b3ee2f7b822180b067a1c9e7fb8fa6fd88dc308 Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Mon, 16 Dec 2013 17:54:41 -0800 Subject: [PATCH 145/231] mention other libraries; show ruby example --- content/docs/guides/send-a-broadcast.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index 700c32d..42e2fc3 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -23,7 +23,7 @@ There are a number of parts to each broadcast message. To illustrate, here's a s The important parts are the **Headline**, **Photo**, **Text** and **Read More Link**. Everything but the headline is optional, but we recommend that your broadcasts contain a compelling image and some context through a summary text body and a link to content. -The easiest way to send a broadcast with the API is via the [ADNPy](http://adnpy.readthedocs.org) Python module or the [adn](https://github.com/adn-rb/adn) Ruby gem. You can also use the HTTP API with your own client, if you'd like. +The easiest way to send a broadcast with the API is via the [ADNPy](http://adnpy.readthedocs.org) Python module, the [adn](https://github.com/adn-rb/adn) Ruby gem, the [appnet.js](https://github.com/duerig/appnet.js) library for Node.js, or the [AppDotNetPHP](https://github.com/jdolitsky/AppDotNetPHP) library. You can also use the HTTP API with your own client, if you'd like. Starting with Python, here's an example of using the ADNPy `BroadcastMessageBuilder` recipe. If you're interested in the specific API calls the library is making behind the scenes, [look at the source](https://github.com/appdotnet/ADNpy/blob/master/adnpy/recipes/broadcast.py). @@ -51,6 +51,21 @@ You can easily attach a photo: builder.photo = '/home/paul/celeryman.gif' ~~~ +Or with the [adn](https://github.com/adn-rb/adn) Ruby gem: + +~~~ ruby +require 'adn' + +ADN.token = 'your access token here' + +builder = ADN::Recipes::BroadcastMessageBuilder.new +builder.channel_id = 24204 +builder.headline = 'sending from ruby' +builder.read_more_link = 'https://app.net/' +builder.photo = '/home/mthurman/oyster-smiling.png' +builder.send +~~~ + If you want to send the equivalent broadcast from the API without using a library, use this curl command: ~~~ sh From a0c2e0f8e6cd0a9b81312cf57f65cbf9e6017878 Mon Sep 17 00:00:00 2001 From: Timo Date: Tue, 17 Dec 2013 16:52:29 +0100 Subject: [PATCH 146/231] the "text" property isn't actually returned if you delete a post --- content/docs/resources/post/lifecycle.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/content/docs/resources/post/lifecycle.md b/content/docs/resources/post/lifecycle.md index 8a2d6e3..e6b712f 100644 --- a/content/docs/resources/post/lifecycle.md +++ b/content/docs/resources/post/lifecycle.md @@ -165,7 +165,6 @@ Delete a Post. The current user must be the ... }, "created_at": "2012-07-16T17:25:47Z", - "text": "@berg FIRST post on this new site #newsocialnetwork", "html": "@berg FIRST post on this new site #newsocialnetwork.", "source": { "client_id": "udxGzAVBdXwGtkHmvswR5MbMEeVnq6n4", @@ -204,4 +203,4 @@ Delete a Post. The current user must be the "code": 200, } } -~~~ \ No newline at end of file +~~~ From f90579957e2d2b31fb2e79aae4210dbc47bc2cbd Mon Sep 17 00:00:00 2001 From: Timo Date: Tue, 17 Dec 2013 17:00:34 +0100 Subject: [PATCH 147/231] the annotations value should be an object not a string --- content/docs/resources/user/profile.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/docs/resources/user/profile.md b/content/docs/resources/user/profile.md index 299db30..0093724 100644 --- a/content/docs/resources/user/profile.md +++ b/content/docs/resources/user/profile.md @@ -37,7 +37,9 @@ If you want to add or update a User's annotations, you may include the optional h["data"]["annotations"] = [ { "type" => "net.app.core.directory.blog", - "value" => "http://mynewblog.com/" + "value" => { + "url" => "http://mynewblog.com/" + } } ] end %> From cfdf63316828903df84fe29e125971acc5fdb97e Mon Sep 17 00:00:00 2001 From: Timo Date: Tue, 17 Dec 2013 20:55:05 +0100 Subject: [PATCH 148/231] "channel" gives an 404 Not found. So I assume that the endpoint channel isn't existing. Changes it to channels --- content/docs/resources/channel/lifecycle.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/resources/channel/lifecycle.md b/content/docs/resources/channel/lifecycle.md index d88bed6..fefcbca 100644 --- a/content/docs/resources/channel/lifecycle.md +++ b/content/docs/resources/channel/lifecycle.md @@ -141,7 +141,7 @@ The current user must be the same user who created the Channel. *Editors cannot <%= general_params_note_for "channel" %> -<%= endpoint "DELETE", "channel/[channel_id]", "User" %> +<%= endpoint "DELETE", "channels/[channel_id]", "User" %> <%= url_params [ ["channel_id", "The id of the Channel to delete."] @@ -149,7 +149,7 @@ The current user must be the same user who created the Channel. *Editors cannot ### Example -> DELETE https://alpha-api.app.net/stream/0/channel/1 +> DELETE https://alpha-api.app.net/stream/0/channels/1 <%= response(:channel) do |h| h["data"]["is_inactive"] = true From d4b547c4d2120d7acbae405a8b8b0258216e391c Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Fri, 7 Mar 2014 13:43:10 -0800 Subject: [PATCH 149/231] A little bit of doc cleanup --- content/docs/basics/messaging.md | 3 +- layouts/default.html | 2 +- layouts/partials/endpoints/app-stream.md | 14 +++--- layouts/partials/endpoints/channel.md | 38 +++++++------- layouts/partials/endpoints/config.md | 2 +- layouts/partials/endpoints/explore-stream.md | 4 +- layouts/partials/endpoints/file.md | 20 ++++---- layouts/partials/endpoints/filter.md | 14 +++--- layouts/partials/endpoints/interaction.md | 2 +- layouts/partials/endpoints/message.md | 14 +++--- layouts/partials/endpoints/place.md | 4 +- layouts/partials/endpoints/post.md | 36 +++++++------- layouts/partials/endpoints/stream-marker.md | 2 +- layouts/partials/endpoints/text-processor.md | 2 +- layouts/partials/endpoints/token.md | 6 +-- layouts/partials/endpoints/user-stream.md | 6 +-- layouts/partials/endpoints/user.md | 52 ++++++++++---------- 17 files changed, 111 insertions(+), 110 deletions(-) diff --git a/content/docs/basics/messaging.md b/content/docs/basics/messaging.md index db4dc77..23e73e8 100644 --- a/content/docs/basics/messaging.md +++ b/content/docs/basics/messaging.md @@ -60,6 +60,7 @@ Messages, channel updates and marker updates are pushed as objects over the stre ## Types -Much like annotation types, channel types are freeform strings; we suggest you use a reversed-domain format for any custom channel types. Core channel types are prefixed with `net.app.core` and may have additional validation imposed by the App.net API. Right now, there's only one core channel type: +Much like annotation types, channel types are freeform strings; we suggest you use a reversed-domain format for any custom channel types. Core channel types are prefixed with `net.app.core` and may have additional validation imposed by the App.net API. Currently defined core channel types are: * [Private Message](/docs/resources/channel/#private-message): net.app.core.pm +* [Broadcast Channel](/docs/resources/channel/#broadcast-channel): net.app.core.broadcast diff --git a/layouts/default.html b/layouts/default.html index 79476f6..7127617 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -79,7 +79,7 @@
    • Resources
        • -
      • All Endpoints
        • +
      • Index
      • User
        • Lookup
          • diff --git a/layouts/partials/endpoints/app-stream.md b/layouts/partials/endpoints/app-stream.md index e8ab28e..24c8be8 100644 --- a/layouts/partials/endpoints/app-stream.md +++ b/layouts/partials/endpoints/app-stream.md @@ -11,38 +11,38 @@ Create an App Stream POST - /stream/0/streams + /stream/0/streams App Retrieve an App Stream GET - /stream/0/streams/[stream_id] + /stream/0/streams/{stream_id} App Update an App Stream PUT - /stream/0/streams/[stream_id] + /stream/0/streams/{stream_id} App Delete an App Stream DELETE - /stream/0/streams/[stream_id] + /stream/0/streams/{stream_id} App Retrieve all App Streams for the current Token GET - /stream/0/streams + /stream/0/streams App Delete all App Streams for the current Token DELETE - /stream/0/streams + /stream/0/streams App - \ No newline at end of file + diff --git a/layouts/partials/endpoints/channel.md b/layouts/partials/endpoints/channel.md index e4f6e97..6ed7c0c 100644 --- a/layouts/partials/endpoints/channel.md +++ b/layouts/partials/endpoints/channel.md @@ -11,115 +11,115 @@ Get current user's subscribed channels GET - /stream/0/channels + /stream/0/channels User Create a Channel POST - /stream/0/channels + /stream/0/channels User Retrieve a Channel GET - /stream/0/channels/[channel_id] + /stream/0/channels/{channel_id} Varies Retrieve multiple Channels GET - /stream/0/channels + /stream/0/channels Any Retrieve my Channels GET - /stream/0/users/me/channels + /stream/0/users/me/channels User Retrieve number of unread PM Channels GET - /stream/0/users/me/channels/pm/num_unread + /stream/0/users/me/channels/pm/num_unread User Retrieve number of unread Broadcast Channels GET - /stream/0/users/me/channels/broadcast/num_unread + /stream/0/users/me/channels/broadcast/num_unread User Mark all Broadcast Channels as read DELETE - /stream/0/users/me/channels/broadcast/num_unread + /stream/0/users/me/channels/broadcast/num_unread User Update a Channel PUT - /stream/0/channels/[channel_id] + /stream/0/channels/{channel_id} User Deactivate a Channel DELETE - /stream/0/channels/[channel_id] + /stream/0/channels/{channel_id} User Subscribe to a Channel POST - /stream/0/channels/[channel_id]/subscribe + /stream/0/channels/{channel_id}/subscribe User Unsubscribe from a Channel DELETE - /stream/0/channels/[channel_id]/subscribe + /stream/0/channels/{channel_id}/subscribe User Retrieve users subscribed to a Channel GET - /stream/0/channels/[channel_id]/subscribers + /stream/0/channels/{channel_id}/subscribers Varies Retrieve user ids subscribed to a Channel GET - /stream/0/channels/[channel_id]/subscribers/ids + /stream/0/channels/{channel_id}/subscribers/ids Varies Retrieve user ids subscribed to multiple Channels GET - /stream/0/channels/subscribers/ids + /stream/0/channels/subscribers/ids Varies Mute a Channel POST - /stream/0/channels/[channel_id]/mute + /stream/0/channels/{channel_id}/mute User Unmute a Channel DELETE - /stream/0/channels/[channel_id]/mute + /stream/0/channels/{channel_id}/mute User Get current user's muted Channels GET - /stream/0/users/me/channels/muted + /stream/0/users/me/channels/muted User Search for Channels GET - /stream/0/channels/search + /stream/0/channels/search User diff --git a/layouts/partials/endpoints/config.md b/layouts/partials/endpoints/config.md index a5eac59..3f50f2b 100644 --- a/layouts/partials/endpoints/config.md +++ b/layouts/partials/endpoints/config.md @@ -11,7 +11,7 @@ Retrieve the Configuration object GET - /stream/0/config + /stream/0/config None diff --git a/layouts/partials/endpoints/explore-stream.md b/layouts/partials/endpoints/explore-stream.md index bbd1d8e..913d478 100644 --- a/layouts/partials/endpoints/explore-stream.md +++ b/layouts/partials/endpoints/explore-stream.md @@ -11,13 +11,13 @@ Retrieve all Explore Streams GET - /stream/0/posts/stream/explore + /stream/0/posts/stream/explore None Retrieve an Explore Stream GET - /stream/0/posts/stream/explore/[slug] + /stream/0/posts/stream/explore/{slug} None diff --git a/layouts/partials/endpoints/file.md b/layouts/partials/endpoints/file.md index 30cc7a4..e049e3e 100644 --- a/layouts/partials/endpoints/file.md +++ b/layouts/partials/endpoints/file.md @@ -11,61 +11,61 @@ Create a File POST - /stream/0/files + /stream/0/files User Create a Derived File POST - /stream/0/files/[file_id]/[derived_key] + /stream/0/files/{file_id}/{derived_key} User Retrieve a File GET - /stream/0/files/[file_id] + /stream/0/files/{file_id} Varies Retrieve multiple Files GET - /stream/0/files + /stream/0/files User Delete a File DELETE - /stream/0/files/[file_id] + /stream/0/files/{file_id} User Retrieve my Files GET - /stream/0/users/me/files + /stream/0/users/me/files User Update a File PUT - /stream/0/files/[file_id] + /stream/0/files/{file_id} User Get File content GET - /stream/0/files/[file_id]/content + /stream/0/files/{file_id}/content User Set File content PUT - /stream/0/files/[file_id]/content + /stream/0/files/{file_id}/content User Set Derived File content PUT - /stream/0/files/[file_id]/content/[derived_key] + /stream/0/files/{file_id}/content/{derived_key} User diff --git a/layouts/partials/endpoints/filter.md b/layouts/partials/endpoints/filter.md index 1b0f695..4cee273 100644 --- a/layouts/partials/endpoints/filter.md +++ b/layouts/partials/endpoints/filter.md @@ -11,38 +11,38 @@ Create a Filter POST - /stream/0/filters + /stream/0/filters User Retrieve a Filter GET - /stream/0/filters/[filter_id] + /stream/0/filters/{filter_id} User Update a Filter PUT - /stream/0/filters/[filter_id] + /stream/0/filters/{filter_id} User Delete a Filter DELETE - /stream/0/filters/[filter_id] + /stream/0/filters/{filter_id} User Get the current User's Filters GET - /stream/0/filters + /stream/0/filters User Delete the current User's Filters DELETE - /stream/0/filters + /stream/0/filters User - \ No newline at end of file + diff --git a/layouts/partials/endpoints/interaction.md b/layouts/partials/endpoints/interaction.md index 817cb8e..5247f5d 100644 --- a/layouts/partials/endpoints/interaction.md +++ b/layouts/partials/endpoints/interaction.md @@ -11,7 +11,7 @@ Retrieve Interactions with the current User GET - /stream/0/users/me/interactions + /stream/0/users/me/interactions User diff --git a/layouts/partials/endpoints/message.md b/layouts/partials/endpoints/message.md index 46e830d..5be7fba 100644 --- a/layouts/partials/endpoints/message.md +++ b/layouts/partials/endpoints/message.md @@ -11,38 +11,38 @@ Retrieve the Messages in a Channel GET - /stream/0/channels/[channel_id]/messages + /stream/0/channels/{channel_id}/messages Varies Create a Message POST - /stream/0/channels/[channel_id]/messages + /stream/0/channels/{channel_id}/messages User Retrieve a Message GET - /stream/0/channels/[channel_id]/messages/[message_id] + /stream/0/channels/{channel_id}/messages/{message_id} Varies Retrieve multiple Messages GET - /stream/0/channels/messages + /stream/0/channels/messages Any Retrieve my Messages GET - /stream/0/users/me/messages + /stream/0/users/me/messages User Delete a Message DELETE - /stream/0/channels/[channel_id]/messages/[message_id] + /stream/0/channels/{channel_id}/messages/{message_id} User - \ No newline at end of file + diff --git a/layouts/partials/endpoints/place.md b/layouts/partials/endpoints/place.md index 5e0959a..fa03fa4 100644 --- a/layouts/partials/endpoints/place.md +++ b/layouts/partials/endpoints/place.md @@ -11,13 +11,13 @@ Retrieve a Place GET - /stream/0/places/[factual_id] + /stream/0/places/{factual_id} Any Search for Places GET - /stream/0/places/search + /stream/0/places/search User diff --git a/layouts/partials/endpoints/post.md b/layouts/partials/endpoints/post.md index b611af5..ff798d2 100644 --- a/layouts/partials/endpoints/post.md +++ b/layouts/partials/endpoints/post.md @@ -11,109 +11,109 @@ Create a Post POST - /stream/0/posts + /stream/0/posts User Retrieve a Post GET - /stream/0/posts/[post_id] + /stream/0/posts/{post_id} None Delete a Post DELETE - /stream/0/posts/[post_id] + /stream/0/posts/{post_id} User Repost a Post POST - /stream/0/posts/[post_id]/repost + /stream/0/posts/{post_id}/repost User Unrepost a Post DELETE - /stream/0/posts/[post_id]/repost + /stream/0/posts/{post_id}/repost User Star a Post POST - /stream/0/posts/[post_id]/star + /stream/0/posts/{post_id}/star User Unstar a Post DELETE - /stream/0/posts/[post_id]/star + /stream/0/posts/{post_id}/star User Retrieve multiple Posts GET - /stream/0/posts + /stream/0/posts Any Retrieve a User's posts GET - /stream/0/users/[user_id]/posts + /stream/0/users/{user_id}/posts None Retrieve a User's starred posts GET - /stream/0/users/[user_id]/stars + /stream/0/users/{user_id}/stars None Retrieve Posts mentioning a User GET - /stream/0/users/[user_id]/mentions + /stream/0/users/{user_id}/mentions Any Retrieve Posts containing a hashtag GET - /stream/0/posts/tag/[hashtag] + /stream/0/posts/tag/{hashtag} None Retrieve replies to a Post GET - /stream/0/posts/[post_id]/replies + /stream/0/posts/{post_id}/replies Any Retrieve a User's personalized stream GET - /stream/0/posts/stream + /stream/0/posts/stream User Retrieve a User's unified stream GET - /stream/0/posts/stream/unified + /stream/0/posts/stream/unified User Retrieve the Global stream GET - /stream/0/posts/stream/global + /stream/0/posts/stream/global None Report a Post POST - /stream/0/posts/{post_id}/report + /stream/0/posts/{post_id}/report User Search for Posts GET - /stream/0/posts/search + /stream/0/posts/search Any diff --git a/layouts/partials/endpoints/stream-marker.md b/layouts/partials/endpoints/stream-marker.md index dde71fb..ed074c0 100644 --- a/layouts/partials/endpoints/stream-marker.md +++ b/layouts/partials/endpoints/stream-marker.md @@ -11,7 +11,7 @@ Update a Stream Marker POST - /stream/0/posts/marker + /stream/0/posts/marker User diff --git a/layouts/partials/endpoints/text-processor.md b/layouts/partials/endpoints/text-processor.md index 328688d..5477f6f 100644 --- a/layouts/partials/endpoints/text-processor.md +++ b/layouts/partials/endpoints/text-processor.md @@ -11,7 +11,7 @@ Process text POST - /stream/0/text/process + /stream/0/text/process Any diff --git a/layouts/partials/endpoints/token.md b/layouts/partials/endpoints/token.md index 9bd9173..77a0e9c 100644 --- a/layouts/partials/endpoints/token.md +++ b/layouts/partials/endpoints/token.md @@ -11,19 +11,19 @@ Retrieve the current token GET - /stream/0/token + /stream/0/token Any Retrieve authorized User IDs for an app GET - /stream/0/apps/me/tokens/user_ids + /stream/0/apps/me/tokens/user_ids App Retrieve authorized User tokens for an app GET - /stream/0/apps/me/tokens + /stream/0/apps/me/tokens App diff --git a/layouts/partials/endpoints/user-stream.md b/layouts/partials/endpoints/user-stream.md index 5685c87..1acaa04 100644 --- a/layouts/partials/endpoints/user-stream.md +++ b/layouts/partials/endpoints/user-stream.md @@ -11,14 +11,14 @@ Delete a User Stream DELETE - /stream/0/users/me/streams/[connection_id] + /stream/0/users/me/streams/{connection_id} User Delete a User Stream subscription DELETE - /stream/0/users/me/streams/[connection_id]/[subscription_id] + /stream/0/users/me/streams/{connection_id}/{subscription_id} User - \ No newline at end of file + diff --git a/layouts/partials/endpoints/user.md b/layouts/partials/endpoints/user.md index dbbdfc7..28a5354 100644 --- a/layouts/partials/endpoints/user.md +++ b/layouts/partials/endpoints/user.md @@ -11,152 +11,152 @@ Retrieve a User GET - /stream/0/users/[user_id] + /stream/0/users/{user_id} None Update a User PUT - /stream/0/users/me + /stream/0/users/me User Partially Update a User PATCH - /stream/0/users/me + /stream/0/users/me User Retrieve a User's avatar image GET - /stream/0/users/[user_id]/avatar + /stream/0/users/{user_id}/avatar None Update a User's avatar image POST - /stream/0/users/me/avatar + /stream/0/users/me/avatar User Retrieve a User's cover image GET - /stream/0/users/[user_id]/cover + /stream/0/users/{user_id}/cover None Update a User's cover image POST - /stream/0/users/me/cover + /stream/0/users/me/cover User Follow a User POST - /stream/0/users/[user_id]/follow + /stream/0/users/{user_id}/follow User Unfollow a User DELETE - /stream/0/users/[user_id]/follow + /stream/0/users/{user_id}/follow User Mute a User POST - /stream/0/users/[user_id]/mute + /stream/0/users/{user_id}/mute User Unmute a User DELETE - /stream/0/users/[user_id]/mute + /stream/0/users/{user_id}/mute User Block a User POST - /stream/0/users/[user_id]/block + /stream/0/users/{user_id}/block User Unblock a User DELETE - /stream/0/users/[user_id]/block + /stream/0/users/{user_id}/block User Retrieve multiple Users GET - /stream/0/users + /stream/0/users Any Search for Users GET - /stream/0/users/search + /stream/0/users/search Any Retrieve Users a User is following GET - /stream/0/users/[user_id]/following + /stream/0/users/{user_id}/following Any Retrieve Users following a User GET - /stream/0/users/[user_id]/followers + /stream/0/users/{user_id}/followers Any Retrieve IDs of Users a User is following GET - /stream/0/users/[user_id]/following/ids + /stream/0/users/{user_id}/following/ids Any Retrieve IDs of Users following a User GET - /stream/0/users/[user_id]/followers/ids + /stream/0/users/{user_id}/followers/ids Any Retrieve muted Users GET - /stream/0/users/[user_id]/muted + /stream/0/users/{user_id}/muted Any Retrieve muted User IDs for multiple Users GET - /stream/0/users/muted/ids + /stream/0/users/muted/ids App Retrieve blocked Users GET - /stream/0/users/[user_id]/blocked + /stream/0/users/{user_id}/blocked Any Retrieve blocked User IDs for multiple Users GET - /stream/0/users/blocked/ids + /stream/0/users/blocked/ids App Retrieve Users who reposted a Post GET - /stream/0/posts/[post_id]/reposters + /stream/0/posts/{post_id}/reposters Any Retrieve Users who starred a Post GET - /stream/0/posts/[post_id]/stars + /stream/0/posts/{post_id}/stars Any - \ No newline at end of file + From b177545cebf5ce6699ad257df4dab1187ade182b Mon Sep 17 00:00:00 2001 From: Ian Mintz Date: Mon, 10 Mar 2014 14:10:12 -0700 Subject: [PATCH 150/231] Styling changes --- Gemfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Gemfile b/Gemfile index 44d5760..f4db781 100644 --- a/Gemfile +++ b/Gemfile @@ -6,7 +6,7 @@ gem 'fssm', '0.2.10' gem 'kramdown', '1.1.0' gem 'coderay', '1.0.9' gem 'pygments.rb', '0.5.2' -gem 'nokogiri', '1.5.9' +gem 'nokogiri', '1.6.1' gem 'rack', '1.5.2' gem 'colored', '1.2' gem 'cri', '2.3.0' From 66faee427a0ca77b3ea64608e45de0e6ee89a033 Mon Sep 17 00:00:00 2001 From: Ian Mintz Date: Mon, 10 Mar 2014 14:26:44 -0700 Subject: [PATCH 151/231] Styling changes for dev docs --- Guardfile | 2 +- content/docs/meta/annotations.md | 2 ++ static/css/style.css | 23 +++++++++++++++++++++++ 3 files changed, 26 insertions(+), 1 deletion(-) diff --git a/Guardfile b/Guardfile index 1279cd9..b5a2d16 100644 --- a/Guardfile +++ b/Guardfile @@ -4,5 +4,5 @@ guard 'nanoc' do watch('nanoc.yaml') # Change this to config.yaml if you use the old config file name watch('Rules') - watch(%r{^(content|layouts|lib)/.*$}) + watch(%r{^(content|layouts|lib|static)/.*$}) end diff --git a/content/docs/meta/annotations.md b/content/docs/meta/annotations.md index b7291b3..c4571f9 100644 --- a/content/docs/meta/annotations.md +++ b/content/docs/meta/annotations.md @@ -145,6 +145,7 @@ We currently define the following core annotations: | [Language](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.language.md) | net.app.core.language | Specifies a language. | | [Embedded Media](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) | net.app.core.oembed | Provides information for displaying an image, video, or other rich content. | | [oEmbed Metadata](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.metadata.md) | net.app.core.oembed.metadata | Provides information for generating an oEmbed representation of a file. | +{: .table .table-striped} We have considered core annotations for the following types of data: @@ -197,3 +198,4 @@ We currently define the following replacement values in annotations: | [File List](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file_list.md) | +net.app.core.file_list | Add information about a list of App.net [Files](/docs/resources/file/) to an annotation. | | [Place](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.place.md) | +net.app.core.place | Add information about a [Place](/docs/resources/place/) to an annotation. | | [User](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.user.md) | +net.app.core.user | Add information about a [User](/docs/resources/user/) to an annotation. | +{: .table .table-striped} diff --git a/static/css/style.css b/static/css/style.css index 5cf1023..64a2ffa 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -104,6 +104,29 @@ body h2, body h3, body h4, body h5 { margin-bottom: .5em; } +blockquote { + font-style: italic; + margin-left: 50px; + line-height: 20px; +} + +table { + border: 1px solid #ddd; +} + +table td, .table th { + border-right: 1px solid #ddd; +} + +code { + border: none; + background-color: transparent; +} + +ul.nav-list ul.nav-list ul.nav-list li a { + padding-left: 50px; +} + p, div.layout-like-p { line-height: 20px; font-size: 14px; From ca223a6274c8e75356cf1d9aba2090c6c1d3bb88 Mon Sep 17 00:00:00 2001 From: Ian Mintz Date: Mon, 10 Mar 2014 14:32:50 -0700 Subject: [PATCH 152/231] Another styling change --- static/css/style.css | 4 ---- 1 file changed, 4 deletions(-) diff --git a/static/css/style.css b/static/css/style.css index 64a2ffa..b15f0ce 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -185,10 +185,6 @@ html.breakpoint-tablet .nav-list { width: auto; } -pre { - border: 1px solid #aaa; -} - pre code { white-space: pre-wrap; } From 5efc8b7703b3d7beab934fef70ab92b231bc27f2 Mon Sep 17 00:00:00 2001 From: Ian Mintz Date: Mon, 10 Mar 2014 14:39:02 -0700 Subject: [PATCH 153/231] And more styling changes --- static/css/style.css | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/static/css/style.css b/static/css/style.css index b15f0ce..7d1d9e5 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -110,6 +110,11 @@ blockquote { line-height: 20px; } +blockquote p { + font-size: 14px; + line-height: 20px; +} + table { border: 1px solid #ddd; } @@ -186,6 +191,7 @@ html.breakpoint-tablet .nav-list { } pre code { + margin-left: 20px; white-space: pre-wrap; } @@ -256,7 +262,7 @@ pre code .il{color:#009999} pre code div .gd,.highlight div .gd .x,.highlight div .gi,.highlight div .gi .x{display:inline-block;width:100%} p code { - word-break: break-all; + word-break: keep-all; white-space: normal; } From ab938ce1f24de9c0b336c5635ea17aac1caa803c Mon Sep 17 00:00:00 2001 From: Ian Mintz Date: Mon, 10 Mar 2014 18:07:56 -0700 Subject: [PATCH 154/231] TOC changes --- static/css/style.css | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/static/css/style.css b/static/css/style.css index 7d1d9e5..36c44eb 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -104,6 +104,10 @@ body h2, body h3, body h4, body h5 { margin-bottom: .5em; } +ul { + list-style-type: square; +} + blockquote { font-style: italic; margin-left: 50px; @@ -128,6 +132,19 @@ code { background-color: transparent; } +#markdown-toc { + color: #ddd; + margin: 0 0 30px 0; + padding: 0 0 0 25px; + font-size: 16px; + line-height: normal; + font-family: 'Montserrat', Helvetica, Arial, sans-serif; +} + +#markdown-toc li { + padding: 2px; +} + ul.nav-list ul.nav-list ul.nav-list li a { padding-left: 50px; } From a25b215e201ccd7e7b57a6bcdf94c274ee0e36fa Mon Sep 17 00:00:00 2001 From: Ian Mintz Date: Mon, 10 Mar 2014 18:07:56 -0700 Subject: [PATCH 155/231] TOC changes and new blocks on title page --- content/index.md | 25 +++++++ static/css/style.css | 80 +++++++++++++++++++++++ static/images/docs-authentication.png | Bin 0 -> 1083 bytes static/images/docs-authentication@2x.png | Bin 0 -> 2191 bytes static/images/docs-broadcast.png | Bin 0 -> 927 bytes static/images/docs-broadcast@2x.png | Bin 0 -> 1795 bytes 6 files changed, 105 insertions(+) create mode 100644 static/images/docs-authentication.png create mode 100644 static/images/docs-authentication@2x.png create mode 100644 static/images/docs-broadcast.png create mode 100644 static/images/docs-broadcast@2x.png diff --git a/content/index.md b/content/index.md index 25d63db..e4f2ff2 100644 --- a/content/index.md +++ b/content/index.md @@ -10,6 +10,31 @@ Welcome aboard! This page is your starting point to getting familiar with the App.net developer platform. Our aim is to get you up and running as quickly and easily as possible. What you see here is always under revision and we always want you to give us your feedback. +
          +
          +
          +
          +
          + +
          +

          Quick Start: Broadcast

          +

          Send a broadcast with the App.net API.

          +
          +
          +
          +
          +
          +
          + +
          +

          Quick Start: Authentication

          +

          Learn how to make authenticated requests to the API.

          +
          +
          +
          +
          +
          + ### Tracking news and announcements To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adnapi). You may also want to subscribe to the [App.net blog](https://broadcast.app.net/26283/appnet-blog/) for general news and [App.net API Updates](https://broadcast.app.net/24368/appnet-api-updates/) for developer related news. diff --git a/static/css/style.css b/static/css/style.css index 7d1d9e5..4233ba7 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -104,6 +104,10 @@ body h2, body h3, body h4, body h5 { margin-bottom: .5em; } +ul { + list-style-type: square; +} + blockquote { font-style: italic; margin-left: 50px; @@ -128,6 +132,19 @@ code { background-color: transparent; } +#markdown-toc { + color: #ddd; + margin: 0 0 30px 0; + padding: 0 0 0 25px; + font-size: 16px; + line-height: normal; + font-family: 'Montserrat', Helvetica, Arial, sans-serif; +} + +#markdown-toc li { + padding: 2px; +} + ul.nav-list ul.nav-list ul.nav-list li a { padding-left: 50px; } @@ -272,4 +289,67 @@ img { display: block; padding: 5px; background-color: #aaa; +} + +.promo-block-wrapper { + margin-top: 30px; + margin-bottom: 30px; + border-top: 1px solid #eee; + border-bottom: 1px solid #eee; +} + +.promo-block { + position: relative; +} + +.promo-block h3 { + margin-top: 20px; + margin-bottom: 15px; + font-size: 18px; +} + +.promo-block h3 hr { + margin-bottom: 0; +} + +.promo-block-inner { + padding: 20px; + -webkit-transition: all 0.2s ease-out; + -moz-transition: all 0.2s ease-out; + -o-transition: all 0.2s ease-out; + transition: all 0.2s ease-out; +} + +.promo-block-inner:hover { + background-color: #ededed; +} + +.promo-block .overlay { + position: absolute; + display: block; + z-index: 1; + top: 0; + left: 0; + width: 100%; + height: 100%; +} + +.promo-block-image { + width: 58px; + height: 58px; + background-size: 58px 58px; + margin: 0 auto 20px auto; + background-image: url(http://github.com/assets/images/docs-broadcast.png); +} + +html.breakpoint-retina .promo-block-image { + background-image: url(http://github.com/assets/images/docs-broadcast@2x.png); +} + +.promo-block-image.authentication { + background-image: url(http://github.com/assets/images/docs-authentication.png); +} + +html.breakpoint-retina .promo-block-image.authentication { + background-image: url(http://github.com/assets/images/docs-authentication@2x.png); } \ No newline at end of file diff --git a/static/images/docs-authentication.png b/static/images/docs-authentication.png new file mode 100644 index 0000000000000000000000000000000000000000..5116558caf1749264931d6e1f7ba38e0435759fb GIT binary patch literal 1083 zcmV-B1jPG^P)s!KmC6W`coPd>j0G1nUPtcChH)xo6y|zO_i~LE}CcCyj z&yQ!u&a#ArgoK2IgoK2IkBQE%h<<(lHl#<7+84ZfqE>$W@pJhh1SJ8F=rO03H*~3} zjY#0)zZH~(JcE!1HMIpSnZdH=dl&zWu#102P+Gikzl;`DdbsK>{$5j?(wJKHF+xtL zjq&QF&6R14@r-U8f0Uq@d;$w(!a`9Do42h(L8f!3A{H5S8B|rK`3(DG^ z+V&ydtyzNIDkNZtzS1(M9{f|)H%d?+%ka0}7P3O`t@!smwe5;({4G}znWLp|+R9b1 zk)Ba`tZkz`TFKnmqIKz}WrUS&^Hid`a#dbZ;ZcH?mH-hV=y8Cc$B_!N@dpcfkLS6g z&$;SraKllvE$oXlGE`#?RssC0O$1$F&zSTvwk+@xd$X2F9uc&{z8QO1bIiF?Me3#C zzjX1VZ=9eid|$D!#sVOja6xVv&Sl@kwa4*|=b1YACsJ6&Z%scjweGDWAuoyKq-9)< zg1xW=60UrF<_Y4L*!K(+b;G-E!?#RWI!C~`qXjRpmum!{GZ9Eef&7_IwDr!TDD8Mb zrq=A3hVtvVOjPBccDmma7V2M+aS{6hwYB*kT zg>nN8m%MQ5^MLtyuN|r=ZT49~{Rb`lYsWq6I~Ph=LaDF#*8~N@mF3Krxz3a-DCmg& zgl{#hVLNy~Vhc>gt%HUMHkU1DSsVY$S-B(1uLn^^l~~+8ELnM!Z$s?6t|h@YUX!Tn z7Fj4%;9q+3pTS!s|BHfI&^x$DiA8yzIzVy+SNnwDJs%+*UQu8zzaenpbBmx-)*S12 z-WDBkw_|m$76Ipu^3d#=neXi$0?NcOUje060qbKgeHN5+RO{W2<9eeI!KH*2>nsA; zx6&&Ph45b2CYJrX*cTJ70yM=!25H&zNXX^fQgPmjeBAfsTtU#DvFM-3HNB*ST|uO( zVC-$cJIZ#Clh}csK#g*ATq_=SXjP6Wjk)zLEP7};d+r)5wU(_2>UEmmGHiELt=JDF z;dJsqE|k49@@-l)At50lAt50lAt52*eehR+0RVFF>R9-v^QHg*002ovPDHLkV1hJ2 B2%i7| literal 0 HcmV?d00001 diff --git a/static/images/docs-authentication@2x.png b/static/images/docs-authentication@2x.png new file mode 100644 index 0000000000000000000000000000000000000000..8611e418adb8d48c116c69ea79a960bfc39a79a3 GIT binary patch literal 2191 zcma*p`6CmI0|xLhAu}dd&9ymarjRT4%7$3>x>J$+S}51DM3cFDOU!-F7&TXUZFC`L zt}x{&$5v6P-iAu9cfNi9g75c-=lT2z&y(%qWDk~rN&o-=FwVi&?YG4LMqKoFdz2~Y z{N@PJ?i|rQDwIeHhz$W?f};XMV7N;GVIgiI0l^6|!y#w@K->^#i}ASn=Bv+(nD?e~ zqJJE z2tfc^yVs9bG-=87_htS9-3Yj44TFe_2&eonqH>drQv};zCRFz)vixkwKetVIXQjK2 zZWn%UIa=(J@r*#4Yw$T;h4uZ97VxLTpgc&qi z!N%6p^2=oD>%(%I-@*m0IfwAfwR}4}$ihppeG5u*&@W#ak~y4B)pbC_(!`DGD{ip^ zEPJ`*c{uo+N9K0l6XRv$dY>1;TB|4i!M#rbg^{o($kGFO8heq~B`!g2AvF3A_CZ%pLK8ZW6xNMVP~1*5 zXy=#^vurD7+SOtofT>jml|^YyZ0Lt{-I~gDooz862=XM6Thkl`7Hk|g{DIhCnhX=u zV(~d5WjjqlraU;q|`#n;I3TU zSfCiz=Kf!scT!wFxCY_fsKr?+FCV}OeGaNbiCq&ZQ*8?)kSk713xE*q@nQvNEwRUR@bm zu4ISd`82E;^~lM0pe*Pv^3?R}(S*-4!2luWDQ*yL6~xdBS`AuMf9AC_Unix=}Cb{mRA>N6Vq9 z!UINWMKhbg)vEN;#W7dGY^6jjQ98fqN*!I;T~ma+nnvMQmClF15avu3ik2VSMOn;p_T>1Hz?~xPF3FvzrW#YAd@W-)ay$;Trmr&uJvjx}*dOFTDCByU#VGR=(N|JPjZ1yh|OE~`?#ok9 zP((}w1{DsLbu?=8THCmN;+ulmDgi0?DDZcM*X%0j=*hhUYP?h zTLsL@K?7y>s+m}JOFFVs(IyN2|qD?T2#61_T;}zI;yVnC~}Nk1zBN z30c_&8z5r#ALStwoe}@G94|!pE?gDR7^5+yL3$jtr)m&zv)TOMy>;o?3*#KcIfYh` zxI_D;+KZWjoa!v9(QYB5uZC!?%r3LpKK(IrxOK9H9ES%aPfaTfTcP<@ zVb50D{6Gr#g}sg}eywcv&J__2qRe)w`(^^fd&Z8E_Rb2<56yBrjW&9zXJ3krt!z)N$tQeOG}FaS6^C)*aRKjlBHKl*b3 literal 0 HcmV?d00001 diff --git a/static/images/docs-broadcast.png b/static/images/docs-broadcast.png new file mode 100644 index 0000000000000000000000000000000000000000..27df4c7330d096dd974de4550a83ac564179bf07 GIT binary patch literal 927 zcmV;Q17Q4#P)tEr&Qo;!cCuk4{AVo_M zB`c!^*?yTSqkq`v()6ZeWNcnD$;$XOxm_1Pp2FdtU1~tK$CF|dKprWQwPJHj(!GR{ zD%Z+M0Y%Af@U$Y3Alt^~IfsEKxq!nO#sy5Qc9d*^r&|~co80-4j7pG_kpd^}l1k)# zlD!9%ugsk{(E!C-^b}81^qH+1h{1Ch-|+K|%X~sIx}r3I#|`?;c9;E$&!Fes#s+lB zCb}gl8cLW7_8Me*#h9&KydDfFGROTytn8IA+`D0t&zaYq*$m0(lKTn3wrtW`38SxR zAzpWCyp|2|XAqz$&3Ar+Nmm9Erd_sz-)|K*OI)yM813_uR>DlOoPGYh+aZ$*0aWWJ zorJN+yr#vVss~dHdA*DVsEMBx2^UH#;gS_Yb7x3KP5nd?mLQ*Taat@4dc7VCP$NGn z5~fWlR~Bb*?hFFd)=!Fr%Z_{2E`8@mFly~50Cxe0Gi8^h%_(!~JA<}qeSX64GGtK4 zthV47k~>2%+UF;^qu%3-E!&3R&X?SL0qyjY(rOuXFL=*u4>~k=dIhTUlae1>i|%FV z)0;jS)%odvs|Dj2!S;49xCjfMyRA>4@BE~;TDSn`1`=K|uQ$;E?ebGst7Xx>EJLvA zgV8QOb+uY1-HZ3!=>=$)pL$v?VbFkk&z-&)-SLyI)!I|~aS3}X;C)v{s-JYNmacoD z+V~Q{J~FRYA%G^1vfc3$`v-cb)iUf}Hq5U<*c>8V{_=}&EV-$_6bYxk8f@P{dG0KF zS}kE9;f6`Ri3TXhbS2*Y4>_S8v}>0&l(3X~6(V=?IB)=3;6_rh>gO!fCh{pjvFdqN zE^o1cjyi0myHL&>^qH6%(6w@&hp1vc6)5J;RFP~YMiPl5oAnrc=?awlGZ!O^#89@B zJE>r=Cka%%y|bl%pv6>ywx$L99COSuhfBN&FaXbHfydtP^o#%i002ovPDHLkV1lNh Bw9x%T22aY*irXwl|ON0X(k2N(Cz*1wfB*6OYx`r|UWfLY{`~FFV~F>?LDyy>^HGs0 zao1k6Q11;w(~~I)e2De_AT%wRqxQ!$ajOBLJRy~N+j;HSK0gm2l%G1~GxIBPYYWTe zX|+$9+YJcihc#ifZ)ApwD)G&5nFiSNkeAvXD0}a zuTE*RmEl*mF+LZT8;49e0QzoFr_7!|L7~@Swb9fGLgT1YP9BUczgB}#K2~d+c$eAp z1VVY>*g1A+CO}dH=x$b$b3Vl^pw-)qHfY@Zpc+y?t+_%JS z#N~wiE=8Me7^_oGtKFWxG*%ff)#r~iRy$X18>N1Ja#!etc#ZripX)K8r<-_Qm0eCGg$9kK&zdelcj0fOOAfxq)?xH zH`fr;$7;u&msi9jd)Dm9l~Ct=r#gH&#CnyY*Tksx(P8A>B`B<-MjZ@RMS*LBMoX<}#3JsC(T&?$ku-cWuLMNtN3_|HpKRDmHSg&O}iEG<- zx%;eig;t^RoymF)Ry*}<+dg-PmA>mQbiR|;+pP+dL>`FfF}K*~qBM0Dt)Tr0VYIAP_V@YW2e5cg3ByMdS23=KY z*^`4pqvt!dZRMN@>iO!Di?e6XqDQ%j^PRNbzm(#v6Bep%bw#yx5#{_vDL@HX&7$JJY|cfM0G;`OYve--8_yHM(E zO39u@TJC^+*R2ApRP2e}wii(#N_vKR=R37lO6`tc2d-_oXq$>XAT(6Ivm7cMy0#^2 z0TMexd*(aa@oPb9TR3FT5*6x|?{rmQB2I0~qV()pBB9Rt&Qb*yqpYyvqRt`+?UC=O z=3tH; z2o00(oT|VyD(!2%)WIAF5IQj5c~*h>Snt|WR#0$9i?jcWN65 zb<20%GYd?|uX(}qFpZ)&ffYxnW4@zKx?Bwj^)82Ll)mS-RD~Mzo#CX*O@Pmy3UgWE zjAQo9O{g~C`4-&vQ0dWPz4u(7ommKV$amBir_Mt@!whAGGm-h=MUD#9<~z+7r#6u+ z&!wXKQ2IoC351dZj@VY~XuX2FI+GG=$#>S{*CLQ=D=Tb3s2OCw(|mF2CQ*62uB@=; zls%IZs>^q3kkp-ccd^6R*83uuB9%hBgPr%oFPzsn6I$<)TlPFhs#1sxyLH)4k`Pn% zM>pb_J9B7ov8_u}A1_1qj00~COP<#wN+BSBBRA3#Up zmaDR-?GS%hEhEdlx7@cKzXp^-s3v;~!fKD8frmn8mizlaYn(tLLKhaR#i*7Gp_;=l z&as5m@=~ZtolU9b>>yN+3RZh1gc1iYo@35+S?V(@bfS5^=DdpWDGAjayeJ_DKudHt zKZRDX+Up{e8r^P6__hQP8YX*6t6ia+c`B5$+bOK}I&!E4);O6HT8sayyBf!mc>n+a l00000000007~@|71_0VEB=czintT8N002ovPDHLkV1j@GZKePK literal 0 HcmV?d00001 From fd5d3e452a6c02474797fbf270fd98191b7cedf2 Mon Sep 17 00:00:00 2001 From: Ian Mintz Date: Mon, 10 Mar 2014 19:21:34 -0700 Subject: [PATCH 156/231] Add blocks to title page --- content/index.md | 8 ++++++-- static/css/style.css | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/content/index.md b/content/index.md index e4f2ff2..3f67974 100644 --- a/content/index.md +++ b/content/index.md @@ -17,7 +17,9 @@ This page is your starting point to getting familiar with the App.net developer
          -

          Quick Start: Broadcast

          +

          + Quick Start: Broadcast
          +

          Send a broadcast with the App.net API.

          @@ -27,7 +29,9 @@ This page is your starting point to getting familiar with the App.net developer
          -

          Quick Start: Authentication

          +

          + Quick Start: Authentication
          +

          Learn how to make authenticated requests to the API.

          diff --git a/static/css/style.css b/static/css/style.css index 4233ba7..c6baca2 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -337,8 +337,8 @@ img { .promo-block-image { width: 58px; height: 58px; - background-size: 58px 58px; margin: 0 auto 20px auto; + background-size: 58px 58px; background-image: url(http://github.com/assets/images/docs-broadcast.png); } From 0cfbd25c13d414d9dc98f926d09a5f4883e3891b Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Tue, 11 Mar 2014 15:31:54 -0700 Subject: [PATCH 157/231] Move channels to sample objects --- content/docs/resources/channel/index.md | 53 +----- content/docs/resources/channel/lifecycle.md | 82 +-------- content/docs/resources/channel/lookup.md | 173 +----------------- content/docs/resources/channel/muting.md | 125 ++----------- content/docs/resources/channel/search.md | 65 +------ .../docs/resources/channel/subscriptions.md | 167 +++-------------- lib/sample_objects.rb | 31 +++- 7 files changed, 86 insertions(+), 610 deletions(-) diff --git a/content/docs/resources/channel/index.md b/content/docs/resources/channel/index.md index 51827d7..bba128f 100644 --- a/content/docs/resources/channel/index.md +++ b/content/docs/resources/channel/index.md @@ -11,54 +11,11 @@ title: "Channel" A Channel is a user created stream of Messages. It controls access to the messages in the channel allowing for (among other things) public, private, and group messaging. For an overview of the App.net messaging API, please see the [Introduction to App.net Messaging](/docs/basics/messaging/). -~~~ js -{ - "counts": { - "messages": 42, - "subscribers": 43 - }, - "has_unread": true, - "id": "1", - "is_inactive": false - "editors": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [], - "you": true - }, - "owner": { - ... - }, - "marker": { - ... - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "recent_message_id": "231", - "recent_message": { - ... - }, - "type": "net.app.core.pm", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "1", - ], - "you": true - }, - "you_can_edit": false, - "you_muted": false, - "you_subscribed": true -} -~~~ +## Example Channel object + +<%= json(:CHANNEL_WITH_MARKER) do |h| + h["writers"]["user_ids"] = ["2", "3"] +end %> ## Fields diff --git a/content/docs/resources/channel/lifecycle.md b/content/docs/resources/channel/lifecycle.md index fefcbca..20c55e2 100644 --- a/content/docs/resources/channel/lifecycle.md +++ b/content/docs/resources/channel/lifecycle.md @@ -29,43 +29,13 @@ Send a JSON document that matches the [Channel schema](/docs/resources/channel/) > > DATA {"type": "com.example.channel", "writers": {"user_ids": ["@berg", "1"]}} -~~~ js -{ - "data": { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "36", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "type": "com.example.channel", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "1", - "2" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": true - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:channel) do |h| + h["data"]["id"] = "2" + h["data"]["readers"]["public"] = false + h["data"]["writers"]["user_ids"] = ["1", "2"] + h["data"].delete("recent_message_id") + h["data"].delete("recent_message") +end %> ## Update a Channel @@ -91,43 +61,7 @@ This endpoint currently works identically for the `PUT` and `PATCH` HTTP methods > > DATA {"readers": {"public": true}} -~~~ js -{ - "data": { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "1", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": false, - "public": true, - "user_ids": [], - "you": true - }, - "type": "com.example.channel", - "writers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [ - "1" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": true - }, - "meta": { - "code": 200 - } -} -~~~ - +<%= response(:channel) %> ## Deactivate a Channel diff --git a/content/docs/resources/channel/lookup.md b/content/docs/resources/channel/lookup.md index 64aac02..e458ed0 100644 --- a/content/docs/resources/channel/lookup.md +++ b/content/docs/resources/channel/lookup.md @@ -21,45 +21,9 @@ Returns a specific [Channel](/docs/resources/channel/). #### Example -> GET https://alpha-api.app.net/stream/0/channels/2 +> GET https://alpha-api.app.net/stream/0/channels/1 -~~~ js -{ - "data": { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "2", - "owner": { - // user object of channel owner - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "recent_message_id": "480", - "type": "net.app.core.pm", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "1" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": true - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:channel) %> ## Retrieve multiple Channels Returns multiple Channels requested by id. At most 200 channels can be requested. Channels which do not exist or which the requesting user does not have authorization to view will not be returned. @@ -80,66 +44,14 @@ Returns multiple Channels requested by id. At most 200 channels can be requested { "data": [ { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "1", - "owner": { - // user object of channel owner - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "recent_message_id": "3094", - "type": "net.app.core.pm", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "8" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": true + "id": "1", // note this is a string + ... }, { - "counts": { - "messages": 42 - }, - "has_unread": false, "id": "2", - "owner": { - // user object of channel owner - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "recent_message_id": "480", - "type": "net.app.core.pm", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "1" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": true + ... } - // Note that channel 6502 is not present as it doesn't exist. + // In this example, Channel 6502 is not present as it doesn't exist. ], "meta": { "code": 200 @@ -160,49 +72,7 @@ Returns a stream of all Channels the current user has created. > GET https://alpha-api.app.net/stream/0/users/me/channels -~~~ js -{ - "data": [ - { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "2", - "owner": { - // user object of channel owner - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "recent_message_id": "3094", - "type": "net.app.core.pm", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "8" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": true - }, - ... - ], - "meta": { - "code": 200, - "max_id": 2, - "min_id": 1, - "more": false - } -} -~~~ +<%= paginated_response(:channel) %> ## Retrieve number of unread PM Channels Returns the current number of `net.app.core.pm` Channels where `has_unread: true` for the current user. @@ -213,15 +83,7 @@ Returns the current number of `net.app.core.pm` Channels where `has_unread: true > GET https://alpha-api.app.net/stream/0/users/me/channels/pm/num_unread -~~~ js -{ - "data": 5, - "meta": { - "code": 200 - } -} -~~~ - +<%= response(5) %> ## Retrieve number of unread Broadcast Channels Returns the current number of `net.app.core.broadcast` Channels where `has_unread: true` for the current user. @@ -232,15 +94,7 @@ Returns the current number of `net.app.core.broadcast` Channels where `has_unrea > GET https://alpha-api.app.net/stream/0/users/me/channels/broadcast/num_unread -~~~ js -{ - "data": 3, - "meta": { - "code": 200 - } -} -~~~ - +<%= response(3) %> ## Mark all Broadcast Channels as read Mark all `net.app.core.broadcast` Channels as read for the current user. @@ -251,11 +105,4 @@ Mark all `net.app.core.broadcast` Channels as read for the current user. > DELETE https://alpha-api.app.net/stream/0/users/me/channels/broadcast/num_unread -~~~ js -{ - "data": 0, - "meta": { - "code": 200 - } -} -~~~ +<%= response(0) %> diff --git a/content/docs/resources/channel/muting.md b/content/docs/resources/channel/muting.md index 3208c94..e13389d 100644 --- a/content/docs/resources/channel/muting.md +++ b/content/docs/resources/channel/muting.md @@ -19,46 +19,9 @@ This endpoint is **not** paginated and does **not** respond to the [general chan > GET https://alpha-api.app.net/stream/0/users/me/channels/muted -~~~ js -{ - "data": [ - { - "counts": { - "messages": 42 - }, - "has_unread": true, - "id": "1", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "type": "net.app.core.pm", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "1", - ], - "you": true - }, - "you_can_edit": false, - "you_muted": true, - "you_subscribed": true - }, - ... - ], - "meta": { - "code": 200, - } -} -~~~ +<%= collection_response(:channel) do |h| + h["data"][0]["you_muted"] = true +end %> ## Mute a Channel @@ -76,43 +39,10 @@ Mute a Channel. If a user doesn't want to see a channel until there is a new mes > POST https://alpha-api.app.net/stream/0/channels/1/mute -~~~ js -{ - "data": { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "1", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [], - "you": true - }, - "type": "com.example", - "writers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [ - "1" - ], - "you": true - }, - "you_can_edit": true, - "you_muted": true, - "you_subscribed": false - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:channel) do |h| + h["data"]["you_muted"] = true + h["data"]["you_subscribed"] = false +end %> ## Unmute a Channel @@ -130,40 +60,7 @@ Unmute a Channel. This allows you to be resubscribed to the channel (but it does > DELETE https://alpha-api.app.net/stream/0/channels/1/mute -~~~ js -{ - "data": { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "1", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [], - "you": true - }, - "type": "com.example", - "writers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [ - "1" - ], - "you": true - }, - "you_can_edit": true, - "you_muted": false, - "you_subscribed": false - }, - "meta": { - "code": 200 - } -} -~~~ \ No newline at end of file +<%= response(:channel) do |h| + h["data"]["you_muted"] = false + h["data"]["you_subscribed"] = false +end %> diff --git a/content/docs/resources/channel/search.md b/content/docs/resources/channel/search.md index e64b92c..1c7bf1f 100644 --- a/content/docs/resources/channel/search.md +++ b/content/docs/resources/channel/search.md @@ -41,63 +41,8 @@ Returns [Channel](/docs/resources/channel/) objects which match a given search q > GET https://alpha-api.app.net/stream/0/channels/search?q=kerbal&order=popularity -~~~ js -{ - "data": [ - ... - { - "counts": { - "messages": 178 - }, - "has_unread": false, - "id": "13797", - "is_inactive": false, - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": false, - "public": true, - "user_ids": [], - "you": true - }, - "recent_message_id": "1222525", - "type": "net.patter-app.room", - "writers": { - "any_user": true, - "immutable": false, - "public": false, - "user_ids": [], - "you": true - }, - "you_can_edit": true, - "you_muted": false, - "you_subscribed": true, - "annotations": [ - { - "type": "net.patter-app.settings", - "value": { - "blurb": "Discussion for the wonderful space simulator "Kerbal Space Program." Rocket designs, missions, anecdotes etc. welcome", - "blurb_id": "417309", - "categories": ["fun"], - "name": "Kerbonauts" - } - }, - { - "type": "net.app.core.fallback_url", - "value": { - "url": "http://patter-app.net/room.html?channel=13797" - } - } - ] - } - ], - "meta": { - "code": 200, - "max_id": "1", - "min_id": "1", - "more": false - } -} -~~~ +<%= paginated_response(:channel) do |h| + h["meta"]["count"] = 1 + h["meta"]["max_id"] = "10000" + h["meta"]["min_id"] = "10000" +end %> diff --git a/content/docs/resources/channel/subscriptions.md b/content/docs/resources/channel/subscriptions.md index b2b7fbe..006c5aa 100644 --- a/content/docs/resources/channel/subscriptions.md +++ b/content/docs/resources/channel/subscriptions.md @@ -23,52 +23,15 @@ The `meta` response will contain unread counts for common channel types. > GET https://alpha-api.app.net/stream/0/channels -~~~ js -{ - "data": [ - { - "counts": { - "messages": 42 - }, - "has_unread": true, - "id": "1", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [], - "you": true - }, - "type": "net.app.core.pm", - "writers": { - "any_user": false, - "immutable": true, - "public": false, - "user_ids": [ - "1", - ], - "you": true - }, - "you_can_edit": false, - "you_subscribed": true - }, - ... - ], - "meta": { - "code": 200, - "max_id": 146, - "min_id": 123, - "more": true, - "unread_counts": { - "net.app.core.pm": 5, - "net.app.core.broadcast": 3 - } +<%= paginated_response(:channel) do |h| + h["meta"]["max_id"] = "146" + h["meta"]["min_id"] = "123" + h["meta"]["more"] = true + h["meta"]["unread_counts"] = { + "net.app.core.pm" => 5, + "net.app.core.broadcast" => 3 } -} -~~~ +end %> ## Subscribe to a Channel @@ -86,42 +49,9 @@ Subscribe to a Channel. This adds it to your [Channel stream](#get-current-users > POST https://alpha-api.app.net/stream/0/channels/1/subscribe -~~~ js -{ - "data": { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "1", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [], - "you": true - }, - "type": "com.example", - "writers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [ - "1" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": true - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:channel) do |h| + h["data"]["you_subscribed"] = true +end %> ## Unsubscribe from a Channel @@ -139,42 +69,10 @@ Unsubscribe from a Channel. This removes it from your [Channel stream](#get-curr > DELETE https://alpha-api.app.net/stream/0/channels/1/subscribe -~~~ js -{ - "data": { - "counts": { - "messages": 42 - }, - "has_unread": false, - "id": "1", - "owner": { - ... - }, - "readers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [], - "you": true - }, - "type": "com.example", - "writers": { - "any_user": false, - "immutable": false, - "public": false, - "user_ids": [ - "1" - ], - "you": true - }, - "you_can_edit": true, - "you_subscribed": false - }, - "meta": { - "code": 200 - } -} -~~~ +<%= response(:channel) do |h| + h["data"]["counts"]["subscribers"] -= 1 + h["data"]["you_subscribed"] = false +end %> ## Retrieve users subscribed to a Channel @@ -214,17 +112,7 @@ Retrieve all the user ids who are subscribed to a Channel. > GET https://alpha-api.app.net/stream/0/channels/1/subscribers -~~~ js -{ - "data": [ - "1", - ... - ], - "meta": { - "code": 200, - } -} -~~~ +<%= response(["1"]) %> ## Retrieve user ids subscribed to multiple Channels @@ -240,20 +128,9 @@ For each requested Channel, retrieve the ids of all Users who are subscribed to > GET https://alpha-api.app.net/stream/0/channels/subscribers/ids?ids=1,2,3,5 -~~~ js -{ - "data": { - "1": [ - "5", - "10" - ], - "2": [ - "5", - "20" - ] // channels 3 and 5 are omitted as if they are not visible or do not exist - }, - "meta": { - "code": 200, - } -} -~~~ +Channels 3 and 5 are omitted as if they are not visible or do not exist + +<%= response({ + "1" => ["5", "10"], + "2" => ["5", "20"] +}) %> diff --git a/lib/sample_objects.rb b/lib/sample_objects.rb index 484f036..69d3591 100644 --- a/lib/sample_objects.rb +++ b/lib/sample_objects.rb @@ -10,6 +10,8 @@ def get_hash(key) h when Array key + when Integer + key # deep copy so we can make any overrides we need for our specific use of this hash else deep_copy(Resources.const_get(key.to_s.upcase)) end @@ -35,7 +37,13 @@ def diff_hash(a, b) if a[k].is_a?(Hash) && b[k].is_a?(Hash) diff[k] = diff_hash(a[k], b[k]) elsif a[k].is_a?(Array) && b[k].is_a?(Array) - diff[k] = a[k].zip(b[k]).map {|el| diff_hash(el[0], el[1])} + diff[k] = a[k].zip(b[k]).map do |el| + if el[0].is_a?(Hash) && el[1].is_a?(Hash) + diff_hash(el[0], el[1]) + else + el + end + end else diff[k] = [a[k], b[k]] end @@ -228,7 +236,7 @@ def paginated_response(key, &block) } } - CHANNEL = { + CHANNEL_WITH_MARKER = { "counts" => { "messages" => 42, "subscribers" => 43 @@ -244,19 +252,30 @@ def paginated_response(key, &block) "user_ids" => [], "you" => true }, + "editors" => { + "any_user" => false, + "immutable" => false, + "public" => false, + "user_ids" => [], + "you" => true + }, + "recent_message_id" => "231", + "recent_message" => "...message object...", "type" => "com.example.channel", "writers" => { "any_user" => false, "immutable" => false, "public" => false, - "user_ids" => [ - "1" - ], + "user_ids" => [], "you" => true }, "you_can_edit" => true, - "you_subscribed" => true + "you_subscribed" => true, + "you_muted" => false, + "marker" => "...marker object..." } + + CHANNEL = CHANNEL_WITH_MARKER.reject {|key, value| key == "marker" } end include Resources::Helpers From 1acf1ebce1de162489cc1aea7428799e5091a754 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Tue, 11 Mar 2014 18:22:05 -0700 Subject: [PATCH 158/231] Hide the search bar --- static/css/style.css | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/static/css/style.css b/static/css/style.css index 5cf1023..cc4ee91 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -247,4 +247,9 @@ img { display: block; padding: 5px; background-color: #aaa; -} \ No newline at end of file +} + +.search-bar-container { + display: none !important; +} + From d556599476762fba29af6c9d92c1c09e8d439e05 Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Tue, 11 Mar 2014 18:22:05 -0700 Subject: [PATCH 159/231] Hide the search bar --- static/css/style.css | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/static/css/style.css b/static/css/style.css index c6baca2..82e3ec4 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -291,6 +291,7 @@ img { background-color: #aaa; } +<<<<<<< mxml/new-docs .promo-block-wrapper { margin-top: 30px; margin-bottom: 30px; @@ -352,4 +353,9 @@ html.breakpoint-retina .promo-block-image { html.breakpoint-retina .promo-block-image.authentication { background-image: url(http://github.com/assets/images/docs-authentication@2x.png); -} \ No newline at end of file +} + +.search-bar-container { + display: none !important; +} + From 62d64b5aabe6be9a16f20db568b167b3992574fc Mon Sep 17 00:00:00 2001 From: Alex Kessinger Date: Wed, 12 Mar 2014 11:31:00 -0700 Subject: [PATCH 160/231] Create a default grids --- layouts/default.html | 1 + static/css/grids.css | 814 +++++++++++++++++++++++++++++++++++++++++++ static/css/style.css | 8 +- 3 files changed, 822 insertions(+), 1 deletion(-) create mode 100644 static/css/grids.css diff --git a/layouts/default.html b/layouts/default.html index 7127617..8d52a71 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -7,6 +7,7 @@ + diff --git a/static/css/grids.css b/static/css/grids.css new file mode 100644 index 0000000..3d33cc1 --- /dev/null +++ b/static/css/grids.css @@ -0,0 +1,814 @@ +p, div.layout-like-p { + margin: 0 0 11px; } + p small, div.layout-like-p small { + font-size: 14px; + color: #999999; } + +.lead { + margin-bottom: 22px; + font-size: 20px; + font-weight: 200; + line-height: 33px; } + +h1, h2, h3, h4, h5, h6 { + margin: 0; + font-family: "Montserrat", "Helvetica Neue", Helvetica, Arial, sans-serif; + font-weight: 400; + color: #706d73; + text-rendering: optimizelegibility; } + h1 small, h2 small, h3 small, h4 small, h5 small, h6 small { + font-weight: normal; + color: #999999; } + +h1 { + font-size: 30px; + line-height: 44px; } + h1 small { + font-size: 18px; } + +h2 { + font-size: 24px; + line-height: 44px; } + h2 small { + font-size: 18px; } + +h3 { + font-size: 18px; + line-height: 33px; } + h3 small { + font-size: 14px; } + +h4, h5, h6 { + line-height: 22px; } + +h4 { + font-size: 14px; } + h4 small { + font-size: 12px; } + +h5 { + font-size: 12px; } + +h6 { + font-size: 11px; + color: #999999; + text-transform: uppercase; } + +.page-header { + padding-bottom: 21px; + margin: 22px 0; + border-bottom: 1px solid #333333; } + +.page-header h1 { + line-height: 1; } + +ul, ol { + padding: 0; + margin: 0 0 11px 25px; } + +ul ul, +ul ol, +ol ol, +ol ul { + margin-bottom: 0; } + +ul { + list-style: disc; } + +ol { + list-style: decimal; } + +li { + line-height: 22px; } + +ul.unstyled, +ol.unstyled { + margin-left: 0; + list-style: none; } + +dl { + margin-bottom: 22px; } + +dt, +dd { + line-height: 22px; } + +dt { + font-weight: bold; + line-height: 21px; } + +dd { + margin-left: 11px; } + +.dl-horizontal dt { + float: left; + width: 120px; + clear: left; + text-align: right; + overflow: hidden; + text-overflow: ellipsis; + white-space: nowrap; } +.dl-horizontal dd { + margin-left: 130px; } + +ul.ul-horizontal li { + display: inline-block; } + +hr { + margin: 22px 0; + border: 0; + border-top: 1px solid #dddddd; } + +strong { + font-weight: bold; } + +em { + font-style: italic; } + +.muted { + color: #999999; } + +.text-warning { + color: #c09853; } + +.text-error { + color: #d44646; } + +.text-info { + color: #d44646; } + +.text-success { + color: #468847; } + +abbr[title] { + cursor: help; + border-bottom: 1px dotted #999999; } + +abbr.initialism { + font-size: 90%; + text-transform: uppercase; } + +blockquote { + padding: 0 0 0 15px; + margin: 0 0 22px; + border-left: 5px solid #dddddd; } + blockquote p { + margin-bottom: 0; + font-size: 16px; + font-weight: 300; + line-height: 27.5px; } + blockquote small { + display: block; + line-height: 22px; + color: #999999; } + blockquote small:before { + content: '\2014 \00A0'; } + blockquote.pull-right { + float: right; + padding-right: 15px; + padding-left: 0; + border-right: 5px solid #dddddd; + border-left: 0; } + blockquote.pull-right p, + blockquote.pull-right small { + text-align: right; } + +q:before, +q:after, +blockquote:before, +blockquote:after { + content: ""; } + +address { + display: block; + margin-bottom: 22px; + font-style: normal; + line-height: 22px; } + +small { + font-size: 100%; } + +.increase-font { + font-size: 130%; } + +cite { + font-style: normal; } + +.hide-textindent { + text-indent: -999em; + overflow: hidden; + text-decoration: none; } + +.danger { + color: #d44646; } + +hr.spacer { + border: none; + margin: 65px; } + +/* +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 3.3.0 +build: 3167 +*/ +.yui3-g { + letter-spacing: -0.31em; + /* webkit: collapse white-space between units */ + *letter-spacing: normal; + /* reset IE < 8 */ + word-spacing: -0.43em; + /* IE < 8 && gecko: collapse white-space between units */ + text-rendering: optimizespeed; + /* Webkit: fixes text-rendering: optimizeLegibility */ } + +/* Opera as of 12 on Windows needs word-spacing. + The ".opera-only" selector is used to prevent actual prefocus styling + and is not required in markup. +*/ +.opera-only :-o-prefocus, +.yui3-g { + word-spacing: -0.43em; } + +.yui3-u { + display: inline-block; + zoom: 1; + *display: inline; + /* IE < 8: fake inline-block */ + letter-spacing: normal; + word-spacing: normal; + vertical-align: top; + text-rendering: auto; } + +.yui3-u-1, +.yui3-u-1-2, +.yui3-u-1-3, +.yui3-u-2-3, +.yui3-u-1-4, +.yui3-u-3-4, +.yui3-u-1-5, +.yui3-u-2-5, +.yui3-u-3-5, +.yui3-u-4-5, +.yui3-u-1-6, +.yui3-u-5-6, +.yui3-u-1-8, +.yui3-u-3-8, +.yui3-u-5-8, +.yui3-u-7-8, +.yui3-u-1-12, +.yui3-u-5-12, +.yui3-u-7-12, +.yui3-u-11-12, +.yui3-u-1-24, +.yui3-u-5-24, +.yui3-u-7-24, +.yui3-u-11-24, +.yui3-u-13-24, +.yui3-u-17-24, +.yui3-u-19-24, +.yui3-u-23-24 { + display: inline-block; + zoom: 1; + *display: inline; + /* IE < 8: fake inline-block */ + letter-spacing: normal; + word-spacing: normal; + vertical-align: top; + text-rendering: auto; } + +.yui3-u-1 { + display: block; + width: auto; } + +.yui3-u-1-2 { + width: 50%; } + +.yui3-u-1-3 { + width: 33.33333%; } + +.yui3-u-2-3 { + width: 66.66666%; } + +.yui3-u-1-4 { + width: 25%; } + +.yui3-u-3-4 { + width: 75%; } + +.yui3-u-1-5 { + width: 20%; } + +.yui3-u-2-5 { + width: 40%; } + +.yui3-u-3-5 { + width: 60%; } + +.yui3-u-4-5 { + width: 80%; } + +.yui3-u-1-6 { + width: 16.656%; } + +.yui3-u-5-6 { + width: 83.33%; } + +.yui3-u-1-8 { + width: 12.5%; } + +.yui3-u-3-8 { + width: 37.5%; } + +.yui3-u-5-8 { + width: 62.5%; } + +.yui3-u-7-8 { + width: 87.5%; } + +.yui3-u-1-12 { + width: 8.3333%; } + +.yui3-u-5-12 { + width: 41.6666%; } + +.yui3-u-7-12 { + width: 58.3333%; } + +.yui3-u-11-12 { + width: 91.6666%; } + +.yui3-u-1-24 { + width: 4.1666%; } + +.yui3-u-5-24 { + width: 20.8333%; } + +.yui3-u-7-24 { + width: 29.1666%; } + +.yui3-u-11-24 { + width: 45.8333%; } + +.yui3-u-13-24 { + width: 54.1666%; } + +.yui3-u-17-24 { + width: 70.8333%; } + +.yui3-u-19-24 { + width: 79.1666%; } + +.yui3-u-23-24 { + width: 95.8333%; } + +.yui3-u-none { + display: none; } + +.yui3-force-block { + display: block !important; } + +.yui3-force-none { + display: none !important; } + +.yui3-pull-left { + float: left; } + +.yui3-pull-right { + float: right; } + +.yui3-pull-none { + float: none; } + +/* Alignment Helpers */ +/* If you want to middle alight a group of yui-u's */ +.va-middle { + vertical-align: middle; } + +.va-top { + vertical-align: top; } + +.va-bottom { + vertical-align: bottom; } + +.ta-left { + text-align: left; } + +.ta-right { + text-align: right; } + +.ta-center { + text-align: center; } + +.yui3-u.table-cell { + display: table-cell; + word-wrap: break-line; + word-break: break-word; } + +.break-line { + word-wrap: break-line; + word-break: break-word; } + +.ellipsis { + text-overflow: ellipsis; + overflow: hidden; + white-space: nowrap; } + +.centered { + margin-left: auto; + margin-right: auto; } + +/* These are superseded in media querires */ +.float-left, .fixed-left { + float: left; } + +.float-right, .fixed-right { + float: right; } + +.mg-b-10 { + margin-bottom: 10px; } + +.mg-b-20 { + margin-bottom: 20px; } + +.mg-b-30 { + margin-bottom: 30px; } + +.mg-b-40 { + margin-bottom: 40px; } + +.mg-t-10 { + margin-top: 10px; } + +.mg-t-20 { + margin-top: 20px; } + +.mg-t-30 { + margin-top: 30px; } + +.mg-t-40 { + margin-top: 40px; } + +.mg-r-10 { + margin-right: 10px; } + +.mg-r-20 { + margin-right: 20px; } + +.mg-r-30 { + margin-right: 30px; } + +.mg-r-40 { + margin-right: 40px; } + +.mg-l-10 { + margin-left: 10px; } + +.fixed-col.icon-showcase { + width: 140px; } +.fixed-col.icon-view { + width: 77px; } +.fixed-col.app-detail-icon { + width: 100px; } +.fixed-col.autocomplete-icon { + width: 60px; } +.fixed-col.button-app-icon { + width: 48px; } + +.flex-col { + float: right; + width: 100%; } + .flex-col.icon-showcase { + margin-left: -140px; } + .flex-col.icon-view { + margin-left: -77px; } + .flex-col.app-detail-icon { + margin-left: -100px; } + .flex-col.autocomplete-icon { + margin-left: -60px; } + .flex-col.button-app-icon { + margin-left: -48px; } + +.icon-showcase .flex-col-inside { + margin-left: 140px; } +.icon-view .flex-col-inside { + margin-left: 77px; } +.app-detail-icon .flex-col-inside { + margin-left: 100px; } +.autocomplete-icon .flex-col-inside { + margin-left: 60px; } +.button-app-icon .flex-col-inside { + margin-left: 48px; } + +.fixed-col-right { + float: right; + position: relative; } + .fixed-col-right.button-col { + width: 106px; } + .fixed-col-right.recommend-button-col { + width: 100px; } + .fixed-col-right.button-action-col { + width: 33px; } + +.flex-col-left { + float: left; + width: 100%; } + .flex-col-left.button-col { + margin-right: -106px; } + .flex-col-left.recommend-button-col { + margin-right: -100px; } + .flex-col-left.button-action-col { + margin-right: -33px; } + +.flex-col-left-inside { + width: auto; + float: none; + position: static; } + .button-col .flex-col-left-inside { + margin-right: 106px; } + .recommend-button-col .flex-col-left-inside { + margin-right: 100px; } + .button-action-col .flex-col-left-inside { + margin-right: 33px; } + +html.breakpoint-phone { + /* + Copyright (c) 2010, Yahoo! Inc. All rights reserved. + Code licensed under the BSD License: + http://developer.yahoo.com/yui/license.html + version: 3.3.0 + build: 3167 + */ + /* Opera as of 12 on Windows needs word-spacing. + The ".opera-only" selector is used to prevent actual prefocus styling + and is not required in markup. + */ } + html.breakpoint-phone .m-yui3-g { + letter-spacing: -0.31em; + /* webkit: collapse white-space between units */ + *letter-spacing: normal; + /* reset IE < 8 */ + word-spacing: -0.43em; + /* IE < 8 && gecko: collapse white-space between units */ + text-rendering: optimizespeed; + /* Webkit: fixes text-rendering: optimizeLegibility */ } + html.breakpoint-phone .opera-only :-o-prefocus, + html.breakpoint-phone .m-yui3-g { + word-spacing: -0.43em; } + html.breakpoint-phone .m-yui3-u { + display: inline-block; + zoom: 1; + *display: inline; + /* IE < 8: fake inline-block */ + letter-spacing: normal; + word-spacing: normal; + vertical-align: top; + text-rendering: auto; } + html.breakpoint-phone .m-yui3-u-1, + html.breakpoint-phone .m-yui3-u-1-2, + html.breakpoint-phone .m-yui3-u-1-3, + html.breakpoint-phone .m-yui3-u-2-3, + html.breakpoint-phone .m-yui3-u-1-4, + html.breakpoint-phone .m-yui3-u-3-4, + html.breakpoint-phone .m-yui3-u-1-5, + html.breakpoint-phone .m-yui3-u-2-5, + html.breakpoint-phone .m-yui3-u-3-5, + html.breakpoint-phone .m-yui3-u-4-5, + html.breakpoint-phone .m-yui3-u-1-6, + html.breakpoint-phone .m-yui3-u-5-6, + html.breakpoint-phone .m-yui3-u-1-8, + html.breakpoint-phone .m-yui3-u-3-8, + html.breakpoint-phone .m-yui3-u-5-8, + html.breakpoint-phone .m-yui3-u-7-8, + html.breakpoint-phone .m-yui3-u-1-12, + html.breakpoint-phone .m-yui3-u-5-12, + html.breakpoint-phone .m-yui3-u-7-12, + html.breakpoint-phone .m-yui3-u-11-12, + html.breakpoint-phone .m-yui3-u-1-24, + html.breakpoint-phone .m-yui3-u-5-24, + html.breakpoint-phone .m-yui3-u-7-24, + html.breakpoint-phone .m-yui3-u-11-24, + html.breakpoint-phone .m-yui3-u-13-24, + html.breakpoint-phone .m-yui3-u-17-24, + html.breakpoint-phone .m-yui3-u-19-24, + html.breakpoint-phone .m-yui3-u-23-24 { + display: inline-block; + zoom: 1; + *display: inline; + /* IE < 8: fake inline-block */ + letter-spacing: normal; + word-spacing: normal; + vertical-align: top; + text-rendering: auto; } + html.breakpoint-phone .m-yui3-u-1 { + display: block; + width: auto; } + html.breakpoint-phone .m-yui3-u-1-2 { + width: 50%; } + html.breakpoint-phone .m-yui3-u-1-3 { + width: 33.33333%; } + html.breakpoint-phone .m-yui3-u-2-3 { + width: 66.66666%; } + html.breakpoint-phone .m-yui3-u-1-4 { + width: 25%; } + html.breakpoint-phone .m-yui3-u-3-4 { + width: 75%; } + html.breakpoint-phone .m-yui3-u-1-5 { + width: 20%; } + html.breakpoint-phone .m-yui3-u-2-5 { + width: 40%; } + html.breakpoint-phone .m-yui3-u-3-5 { + width: 60%; } + html.breakpoint-phone .m-yui3-u-4-5 { + width: 80%; } + html.breakpoint-phone .m-yui3-u-1-6 { + width: 16.656%; } + html.breakpoint-phone .m-yui3-u-5-6 { + width: 83.33%; } + html.breakpoint-phone .m-yui3-u-1-8 { + width: 12.5%; } + html.breakpoint-phone .m-yui3-u-3-8 { + width: 37.5%; } + html.breakpoint-phone .m-yui3-u-5-8 { + width: 62.5%; } + html.breakpoint-phone .m-yui3-u-7-8 { + width: 87.5%; } + html.breakpoint-phone .m-yui3-u-1-12 { + width: 8.3333%; } + html.breakpoint-phone .m-yui3-u-5-12 { + width: 41.6666%; } + html.breakpoint-phone .m-yui3-u-7-12 { + width: 58.3333%; } + html.breakpoint-phone .m-yui3-u-11-12 { + width: 91.6666%; } + html.breakpoint-phone .m-yui3-u-1-24 { + width: 4.1666%; } + html.breakpoint-phone .m-yui3-u-5-24 { + width: 20.8333%; } + html.breakpoint-phone .m-yui3-u-7-24 { + width: 29.1666%; } + html.breakpoint-phone .m-yui3-u-11-24 { + width: 45.8333%; } + html.breakpoint-phone .m-yui3-u-13-24 { + width: 54.1666%; } + html.breakpoint-phone .m-yui3-u-17-24 { + width: 70.8333%; } + html.breakpoint-phone .m-yui3-u-19-24 { + width: 79.1666%; } + html.breakpoint-phone .m-yui3-u-23-24 { + width: 95.8333%; } + html.breakpoint-phone .m-yui3-u-none { + display: none; } + html.breakpoint-phone .m-yui3-force-block { + display: block !important; } + html.breakpoint-phone .m-yui3-force-none { + display: none !important; } + html.breakpoint-phone .m-yui3-pull-left { + float: left; } + html.breakpoint-phone .m-yui3-pull-right { + float: right; } + html.breakpoint-phone .m-yui3-pull-none { + float: none; } + +html.breakpoint-tablet { + /* + Copyright (c) 2010, Yahoo! Inc. All rights reserved. + Code licensed under the BSD License: + http://developer.yahoo.com/yui/license.html + version: 3.3.0 + build: 3167 + */ + /* Opera as of 12 on Windows needs word-spacing. + The ".opera-only" selector is used to prevent actual prefocus styling + and is not required in markup. + */ } + html.breakpoint-tablet .t-yui3-g { + letter-spacing: -0.31em; + /* webkit: collapse white-space between units */ + *letter-spacing: normal; + /* reset IE < 8 */ + word-spacing: -0.43em; + /* IE < 8 && gecko: collapse white-space between units */ + text-rendering: optimizespeed; + /* Webkit: fixes text-rendering: optimizeLegibility */ } + html.breakpoint-tablet .opera-only :-o-prefocus, + html.breakpoint-tablet .t-yui3-g { + word-spacing: -0.43em; } + html.breakpoint-tablet .t-yui3-u { + display: inline-block; + zoom: 1; + *display: inline; + /* IE < 8: fake inline-block */ + letter-spacing: normal; + word-spacing: normal; + vertical-align: top; + text-rendering: auto; } + html.breakpoint-tablet .t-yui3-u-1, + html.breakpoint-tablet .t-yui3-u-1-2, + html.breakpoint-tablet .t-yui3-u-1-3, + html.breakpoint-tablet .t-yui3-u-2-3, + html.breakpoint-tablet .t-yui3-u-1-4, + html.breakpoint-tablet .t-yui3-u-3-4, + html.breakpoint-tablet .t-yui3-u-1-5, + html.breakpoint-tablet .t-yui3-u-2-5, + html.breakpoint-tablet .t-yui3-u-3-5, + html.breakpoint-tablet .t-yui3-u-4-5, + html.breakpoint-tablet .t-yui3-u-1-6, + html.breakpoint-tablet .t-yui3-u-5-6, + html.breakpoint-tablet .t-yui3-u-1-8, + html.breakpoint-tablet .t-yui3-u-3-8, + html.breakpoint-tablet .t-yui3-u-5-8, + html.breakpoint-tablet .t-yui3-u-7-8, + html.breakpoint-tablet .t-yui3-u-1-12, + html.breakpoint-tablet .t-yui3-u-5-12, + html.breakpoint-tablet .t-yui3-u-7-12, + html.breakpoint-tablet .t-yui3-u-11-12, + html.breakpoint-tablet .t-yui3-u-1-24, + html.breakpoint-tablet .t-yui3-u-5-24, + html.breakpoint-tablet .t-yui3-u-7-24, + html.breakpoint-tablet .t-yui3-u-11-24, + html.breakpoint-tablet .t-yui3-u-13-24, + html.breakpoint-tablet .t-yui3-u-17-24, + html.breakpoint-tablet .t-yui3-u-19-24, + html.breakpoint-tablet .t-yui3-u-23-24 { + display: inline-block; + zoom: 1; + *display: inline; + /* IE < 8: fake inline-block */ + letter-spacing: normal; + word-spacing: normal; + vertical-align: top; + text-rendering: auto; } + html.breakpoint-tablet .t-yui3-u-1 { + display: block; + width: auto; } + html.breakpoint-tablet .t-yui3-u-1-2 { + width: 50%; } + html.breakpoint-tablet .t-yui3-u-1-3 { + width: 33.33333%; } + html.breakpoint-tablet .t-yui3-u-2-3 { + width: 66.66666%; } + html.breakpoint-tablet .t-yui3-u-1-4 { + width: 25%; } + html.breakpoint-tablet .t-yui3-u-3-4 { + width: 75%; } + html.breakpoint-tablet .t-yui3-u-1-5 { + width: 20%; } + html.breakpoint-tablet .t-yui3-u-2-5 { + width: 40%; } + html.breakpoint-tablet .t-yui3-u-3-5 { + width: 60%; } + html.breakpoint-tablet .t-yui3-u-4-5 { + width: 80%; } + html.breakpoint-tablet .t-yui3-u-1-6 { + width: 16.656%; } + html.breakpoint-tablet .t-yui3-u-5-6 { + width: 83.33%; } + html.breakpoint-tablet .t-yui3-u-1-8 { + width: 12.5%; } + html.breakpoint-tablet .t-yui3-u-3-8 { + width: 37.5%; } + html.breakpoint-tablet .t-yui3-u-5-8 { + width: 62.5%; } + html.breakpoint-tablet .t-yui3-u-7-8 { + width: 87.5%; } + html.breakpoint-tablet .t-yui3-u-1-12 { + width: 8.3333%; } + html.breakpoint-tablet .t-yui3-u-5-12 { + width: 41.6666%; } + html.breakpoint-tablet .t-yui3-u-7-12 { + width: 58.3333%; } + html.breakpoint-tablet .t-yui3-u-11-12 { + width: 91.6666%; } + html.breakpoint-tablet .t-yui3-u-1-24 { + width: 4.1666%; } + html.breakpoint-tablet .t-yui3-u-5-24 { + width: 20.8333%; } + html.breakpoint-tablet .t-yui3-u-7-24 { + width: 29.1666%; } + html.breakpoint-tablet .t-yui3-u-11-24 { + width: 45.8333%; } + html.breakpoint-tablet .t-yui3-u-13-24 { + width: 54.1666%; } + html.breakpoint-tablet .t-yui3-u-17-24 { + width: 70.8333%; } + html.breakpoint-tablet .t-yui3-u-19-24 { + width: 79.1666%; } + html.breakpoint-tablet .t-yui3-u-23-24 { + width: 95.8333%; } + html.breakpoint-tablet .t-yui3-u-none { + display: none; } + html.breakpoint-tablet .t-yui3-force-block { + display: block !important; } + html.breakpoint-tablet .t-yui3-force-none { + display: none !important; } + html.breakpoint-tablet .t-yui3-pull-left { + float: left; } + html.breakpoint-tablet .t-yui3-pull-right { + float: right; } + html.breakpoint-tablet .t-yui3-pull-none { + float: none; } + +html.breakpoint-tablet .float-right, html.breakpoint-tablet .float-left, html.breakpoint-phone .float-right, html.breakpoint-phone .float-left { + float: none; } diff --git a/static/css/style.css b/static/css/style.css index 82e3ec4..e02147f 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -291,7 +291,7 @@ img { background-color: #aaa; } -<<<<<<< mxml/new-docs + .promo-block-wrapper { margin-top: 30px; margin-bottom: 30px; @@ -359,3 +359,9 @@ html.breakpoint-retina .promo-block-image.authentication { display: none !important; } +.container { + width:1152px; + margin-right:auto; + margin-left:auto; + *zoom:1 +} From 9faecbfbf7121b7b50ae72784b13c45ef4952fe0 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 12 Mar 2014 11:57:51 -0700 Subject: [PATCH 161/231] Rip out our old redirection system now that we control the server This now will output a file into output/nginx.conf that should be included in the nginx config for the docs server and deleted on deployment. --- Rules | 14 +++++++------- config.yaml | 30 +++++++++++++++--------------- layouts/redirect.html.erb | 12 ------------ lib/redirector.rb | 24 ------------------------ 4 files changed, 22 insertions(+), 58 deletions(-) delete mode 100644 layouts/redirect.html.erb delete mode 100644 lib/redirector.rb diff --git a/Rules b/Rules index 66132c2..50cdd01 100644 --- a/Rules +++ b/Rules @@ -13,15 +13,11 @@ # item, use the pattern “/about/*/”; “/about/*” will also select the parent, # because “*” matches zero or more characters. -# This redirect stuff is inspired by https://gist.github.com/maxim/1782458 -preprocess do - Redirector.generate(config[:redirects], items) -end - -compile '/docs/resources/stream/*' do +compile '/static/*' do end -compile '/static/*' do +compile '/nginx' do + filter :erb, :trim_mode =>"<>" end compile '*' do @@ -35,6 +31,10 @@ compile '*' do end end +route '/nginx' do + '/nginx.conf' +end + route '/static/*' do '/assets'+item.identifier[7..-2] end diff --git a/config.yaml b/config.yaml index d11f7dd..0a0831c 100644 --- a/config.yaml +++ b/config.yaml @@ -70,22 +70,22 @@ data_sources: # Configuration for the “watch” command, which watches a site for changes and # recompiles if necessary. watcher: - # A list of directories to watch for changes. When editing this, make sure - # that the “output/” and “tmp/” directories are _not_ included in this list, - # because recompiling the site will cause these directories to change, which - # will cause the site to be recompiled, which will cause these directories - # to change, which will cause the site to be recompiled again, and so on. - dirs_to_watch: [ 'content', 'layouts', 'lib' ] + # A list of directories to watch for changes. When editing this, make sure + # that the “output/” and “tmp/” directories are _not_ included in this list, + # because recompiling the site will cause these directories to change, which + # will cause the site to be recompiled, which will cause these directories + # to change, which will cause the site to be recompiled again, and so on. + dirs_to_watch: [ 'content', 'layouts', 'lib' ] - # A list of single files to watch for changes. As mentioned above, don’t put - # any files from the “output/” or “tmp/” directories in here. - files_to_watch: [ 'config.yaml', 'Rules' ] + # A list of single files to watch for changes. As mentioned above, don’t put + # any files from the “output/” or “tmp/” directories in here. + files_to_watch: [ 'config.yaml', 'Rules' ] - # When to send notifications (using Growl or notify-send). - notify_on_compilation_success: true - notify_on_compilation_failure: true + # When to send notifications (using Growl or notify-send). + notify_on_compilation_success: true + notify_on_compilation_failure: true redirects: - # format is current url, then list of old alias - - /docs/resources/app-stream/: - - /docs/resources/stream/ + - + from: /docs/resources/stream/(.*) + to: /docs/resources/app-stream/$1 diff --git a/layouts/redirect.html.erb b/layouts/redirect.html.erb deleted file mode 100644 index ffd1285..0000000 --- a/layouts/redirect.html.erb +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - <%= redirect[:title] %> - - - -

          This page has moved to <%= redirect[:url] %>.

          - - diff --git a/lib/redirector.rb b/lib/redirector.rb deleted file mode 100644 index d87cc03..0000000 --- a/lib/redirector.rb +++ /dev/null @@ -1,24 +0,0 @@ -require 'erb' - -# Based on https://gist.github.com/maxim/1782458 -class Redirector - def self.generate(redirects, items) - redirect_template = ERB.new(File.read('layouts/redirect.html.erb')) - - redirects.each do |pairs| - pairs.each_pair do |url, aliases| - url = url.to_s - items.each do |item| - if item.identifier.start_with? url - new_url = item.identifier - aliases.each do |alias_url| - old_url = new_url.gsub(url, alias_url) - redirect = {:url => new_url, :title => item[:title]} - items << Nanoc3::Item.new(redirect_template.result(binding), { :redirect => true }, old_url) - end - end - end - end - end - end -end From 046110e80b395a7d03c4a0ebd696d222ab615d41 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 12 Mar 2014 13:37:55 -0700 Subject: [PATCH 162/231] Forgot a the nginx rewrite file --- content/nginx.conf.erb | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 content/nginx.conf.erb diff --git a/content/nginx.conf.erb b/content/nginx.conf.erb new file mode 100644 index 0000000..bc2ceb3 --- /dev/null +++ b/content/nginx.conf.erb @@ -0,0 +1,8 @@ +<% if @site.config[:redirects] %> +# Set up URL redirects +<% @site.config[:redirects].each do |h| %> +<% unless h[:from].include? '"' or h[:to].include? ';' %> +rewrite "<%= h[:from] %>" "<%= h[:to] %>" redirect; +<% end %> +<% end %> +<% end %> \ No newline at end of file From dae699b6d776d308c097850eda4a7181e7a0de7d Mon Sep 17 00:00:00 2001 From: petec Date: Thu, 13 Mar 2014 20:00:41 -0400 Subject: [PATCH 163/231] Fix link to the app management settings --- content/docs/guides/create-an-app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/docs/guides/create-an-app.md b/content/docs/guides/create-an-app.md index 3307c87..0db2d96 100644 --- a/content/docs/guides/create-an-app.md +++ b/content/docs/guides/create-an-app.md @@ -47,7 +47,7 @@ You can also generate your self an access token. There are a few ways to get an access token, but the easiest way to get an access token for personal use or experimentation is to generate one from your app detail page. -To see a list of your current apps visit [account.app.net/settings/developer/.](https://account.app.net/settings/developer/) +To see a list of your current apps visit [account.app.net/developer/apps/](https://account.app.net/developer/apps/) ![Your Apps Dashboard](https://files.app.net/01qlWgpd.png) From b7d0475e7c078c175916394aeafc4433b0d5ed1c Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Fri, 14 Mar 2014 16:44:39 -0700 Subject: [PATCH 164/231] Big docs reorganization and adding new guides --- Gemfile | 1 + Guardfile | 2 +- config.yaml | 29 ++-- content/docs/guides/create-a-post.md | 48 +++++++ content/docs/guides/create-an-app.md | 27 ++-- content/docs/guides/getting-started.md | 55 ++++++++ content/docs/{basics => guides}/messaging.md | 14 +- content/docs/guides/send-a-broadcast.md | 8 +- content/docs/guides/using-annotations.md | 121 +++++++++++++++++ content/docs/libraries.md | 58 ++++++++ content/index.md | 45 ++----- .../authentication/authorize-with-appnet.md | 4 +- .../authentication/flows/app-access-token.md | 0 .../authentication/flows/password.md | 0 content/reference/authentication/flows/sdk.md | 20 +++ .../authentication/flows/web.md | 2 +- .../authentication/identity-delegation.md | 2 +- .../authentication/index.md | 25 +++- content/reference/index.md | 6 + .../make-request}/data-formats.md | 0 .../make-request}/migrations.md | 0 .../make-request}/pagination.md | 16 +-- .../make-request}/rate-limits.md | 0 .../make-request}/responses.md | 20 +-- .../{docs => reference}/meta/annotations.md | 106 ++++----------- content/{docs => reference}/meta/entities.md | 4 +- content/{docs => reference}/other/feeds.md | 8 +- content/{docs => reference}/other/oembed.md | 0 .../{docs => reference}/other/web-intents.md | 0 .../resources/app-stream/index.md | 18 +-- .../resources/app-stream/lifecycle.md | 22 +-- .../resources/channel/index.md | 61 +++++---- .../resources/channel/lifecycle.md | 10 +- .../resources/channel/lookup.md | 2 +- .../resources/channel/muting.md | 6 +- .../resources/channel/search.md | 2 +- .../resources/channel/subscriptions.md | 2 +- .../resources/config/index.md | 16 +-- .../resources/explore/index.md | 0 .../resources/file/content.md | 4 +- .../resources/file/index.md | 22 +-- .../resources/file/lifecycle.md | 12 +- .../resources/file/lookup.md | 2 +- .../resources/filter/index.md | 2 +- .../resources/filter/lifecycle.md | 20 +-- .../{docs => reference}/resources/index.md | 2 +- .../resources/interaction/index.md | 4 +- .../resources/message/index.md | 22 +-- .../resources/message/lifecycle.md | 12 +- .../resources/message/lookup.md | 2 +- .../resources/place/index.md | 4 +- .../resources/post/index.md | 28 ++-- .../resources/post/lifecycle.md | 10 +- .../resources/post/lookup.md | 2 +- .../resources/post/replies.md | 2 +- .../resources/post/report.md | 0 .../resources/post/reposts.md | 2 +- .../resources/post/search.md | 2 +- .../resources/post/stars.md | 4 +- .../resources/post/streams.md | 12 +- .../resources/stream-marker/index.md | 6 +- .../resources/text-processor/index.md | 2 +- .../resources/token/index.md | 8 +- .../resources/user-stream/index.md | 6 +- .../resources/user-stream/lifecycle.md | 10 +- .../resources/user/blocking.md | 6 +- .../resources/user/following.md | 10 +- .../resources/user/index.md | 14 +- .../resources/user/lookup.md | 2 +- .../resources/user/muting.md | 4 +- .../resources/user/post-interactions.md | 0 .../resources/user/profile.md | 10 +- layouts/default.html | 126 +----------------- layouts/partials/endpoints/app-stream.md | 12 +- layouts/partials/endpoints/channel.md | 38 +++--- layouts/partials/endpoints/config.md | 2 +- layouts/partials/endpoints/explore-stream.md | 4 +- layouts/partials/endpoints/file.md | 20 +-- layouts/partials/endpoints/filter.md | 12 +- layouts/partials/endpoints/interaction.md | 2 +- layouts/partials/endpoints/message.md | 12 +- layouts/partials/endpoints/place.md | 4 +- layouts/partials/endpoints/post.md | 36 ++--- layouts/partials/endpoints/stream-marker.md | 2 +- layouts/partials/endpoints/text-processor.md | 2 +- layouts/partials/endpoints/token.md | 6 +- layouts/partials/endpoints/user-stream.md | 4 +- layouts/partials/endpoints/user.md | 50 +++---- layouts/partials/reference_nav.html | 97 ++++++++++++++ layouts/partials/top_nav.html | 20 +++ lib/helpers.rb | 17 ++- 91 files changed, 858 insertions(+), 616 deletions(-) create mode 100644 content/docs/guides/create-a-post.md create mode 100644 content/docs/guides/getting-started.md rename content/docs/{basics => guides}/messaging.md (78%) create mode 100644 content/docs/guides/using-annotations.md create mode 100644 content/docs/libraries.md rename content/{docs => reference}/authentication/authorize-with-appnet.md (89%) rename content/{docs => reference}/authentication/flows/app-access-token.md (100%) rename content/{docs => reference}/authentication/flows/password.md (100%) create mode 100644 content/reference/authentication/flows/sdk.md rename content/{docs => reference}/authentication/flows/web.md (96%) rename content/{docs => reference}/authentication/identity-delegation.md (98%) rename content/{docs => reference}/authentication/index.md (71%) create mode 100644 content/reference/index.md rename content/{docs/basics => reference/make-request}/data-formats.md (100%) rename content/{docs/basics => reference/make-request}/migrations.md (100%) rename content/{docs/basics => reference/make-request}/pagination.md (85%) rename content/{docs/basics => reference/make-request}/rate-limits.md (100%) rename content/{docs/basics => reference/make-request}/responses.md (78%) rename content/{docs => reference}/meta/annotations.md (68%) rename content/{docs => reference}/meta/entities.md (95%) rename content/{docs => reference}/other/feeds.md (91%) rename content/{docs => reference}/other/oembed.md (100%) rename content/{docs => reference}/other/web-intents.md (100%) rename content/{docs => reference}/resources/app-stream/index.md (90%) rename content/{docs => reference}/resources/app-stream/lifecycle.md (77%) rename content/{docs => reference}/resources/channel/index.md (63%) rename content/{docs => reference}/resources/channel/lifecycle.md (63%) rename content/{docs => reference}/resources/channel/lookup.md (97%) rename content/{docs => reference}/resources/channel/muting.md (80%) rename content/{docs => reference}/resources/channel/search.md (78%) rename content/{docs => reference}/resources/channel/subscriptions.md (97%) rename content/{docs => reference}/resources/config/index.md (81%) rename content/{docs => reference}/resources/explore/index.md (100%) rename content/{docs => reference}/resources/file/content.md (94%) rename content/{docs => reference}/resources/file/index.md (91%) rename content/{docs => reference}/resources/file/lifecycle.md (78%) rename content/{docs => reference}/resources/file/lookup.md (95%) rename content/{docs => reference}/resources/filter/index.md (98%) rename content/{docs => reference}/resources/filter/lifecycle.md (76%) rename content/{docs => reference}/resources/index.md (90%) rename content/{docs => reference}/resources/interaction/index.md (95%) rename content/{docs => reference}/resources/message/index.md (79%) rename content/{docs => reference}/resources/message/lifecycle.md (85%) rename content/{docs => reference}/resources/message/lookup.md (98%) rename content/{docs => reference}/resources/place/index.md (97%) rename content/{docs => reference}/resources/post/index.md (85%) rename content/{docs => reference}/resources/post/lifecycle.md (84%) rename content/{docs => reference}/resources/post/lookup.md (97%) rename content/{docs => reference}/resources/post/replies.md (87%) rename content/{docs => reference}/resources/post/report.md (100%) rename content/{docs => reference}/resources/post/reposts.md (98%) rename content/{docs => reference}/resources/post/search.md (93%) rename content/{docs => reference}/resources/post/stars.md (94%) rename content/{docs => reference}/resources/post/streams.md (93%) rename content/{docs => reference}/resources/stream-marker/index.md (83%) rename content/{docs => reference}/resources/text-processor/index.md (66%) rename content/{docs => reference}/resources/token/index.md (89%) rename content/{docs => reference}/resources/user-stream/index.md (94%) rename content/{docs => reference}/resources/user-stream/lifecycle.md (64%) rename content/{docs => reference}/resources/user/blocking.md (78%) rename content/{docs => reference}/resources/user/following.md (85%) rename content/{docs => reference}/resources/user/index.md (91%) rename content/{docs => reference}/resources/user/lookup.md (95%) rename content/{docs => reference}/resources/user/muting.md (83%) rename content/{docs => reference}/resources/user/post-interactions.md (100%) rename content/{docs => reference}/resources/user/profile.md (82%) create mode 100644 layouts/partials/reference_nav.html create mode 100644 layouts/partials/top_nav.html diff --git a/Gemfile b/Gemfile index f4db781..3d86ed9 100644 --- a/Gemfile +++ b/Gemfile @@ -15,3 +15,4 @@ gem 'yajl-ruby', '1.1.0' gem 'listen', '1.2.2' gem 'guard-nanoc', '1.0.1' gem 'rb-readline' +gem 'w3c_validators' \ No newline at end of file diff --git a/Guardfile b/Guardfile index b5a2d16..1dcffed 100644 --- a/Guardfile +++ b/Guardfile @@ -2,7 +2,7 @@ # More info at https://github.com/guard/guard#readme guard 'nanoc' do - watch('nanoc.yaml') # Change this to config.yaml if you use the old config file name + watch('config.yaml') # Change this to config.yaml if you use the old config file name watch('Rules') watch(%r{^(content|layouts|lib|static)/.*$}) end diff --git a/config.yaml b/config.yaml index 0a0831c..ecd98bb 100644 --- a/config.yaml +++ b/config.yaml @@ -67,25 +67,16 @@ data_sources: type: static items_root: /static -# Configuration for the “watch” command, which watches a site for changes and -# recompiles if necessary. -watcher: - # A list of directories to watch for changes. When editing this, make sure - # that the “output/” and “tmp/” directories are _not_ included in this list, - # because recompiling the site will cause these directories to change, which - # will cause the site to be recompiled, which will cause these directories - # to change, which will cause the site to be recompiled again, and so on. - dirs_to_watch: [ 'content', 'layouts', 'lib' ] - - # A list of single files to watch for changes. As mentioned above, don’t put - # any files from the “output/” or “tmp/” directories in here. - files_to_watch: [ 'config.yaml', 'Rules' ] - - # When to send notifications (using Growl or notify-send). - notify_on_compilation_success: true - notify_on_compilation_failure: true - redirects: + - + from: /docs/basics/messaging/ + to: /docs/guides/messaging/ - from: /docs/resources/stream/(.*) - to: /docs/resources/app-stream/$1 + to: /reference/resources/app-stream/$1 + - + from: /docs/(resources|authentication|meta|other)/(.*) + to: /reference/$1/$2 + - + from: /docs/basics/(.*) + to: /reference/make-request/$1 diff --git a/content/docs/guides/create-a-post.md b/content/docs/guides/create-a-post.md new file mode 100644 index 0000000..c96f7db --- /dev/null +++ b/content/docs/guides/create-a-post.md @@ -0,0 +1,48 @@ +--- +title: "Create a Post" +--- + +# Creating a Post via the API + +<%= access_token_required_note %> + +A [Post](/reference/resources/post) is the microblogging primitive of the App.net API. When a user creates a post, it appears in all of their follower's streams. Posts can have images, links, and annotations but at their simplest, they just contain a piece of text. + +* TOC +{:toc} + +## Create a post + +The easiest way to create a post is to use [one of the API libraries](/docs/libraries). + +Using [adnpy](/docs/libraries#python) +~~~ python +import adnpy + +# Set the default access token for API calls. +adnpy.api.add_authorization_token('your access token here') + +# Create a post +post = adnpy.api.create_post(data={'text':'Hello App.net from Python!'}) +~~~ + +Or with the [adn](/docs/libraries#ruby) Ruby gem: + +~~~ ruby +require 'adn' + +ADN.token = 'your access token here' +post = ADN::Post.send_post(:text => "Hello App.net from Ruby!") +~~~ + +If you want to send the equivalent broadcast from the API without using a library, use this curl command: + +~~~ sh +curl -X POST -H "Authorization: Bearer " \ + -H "X-adn-pretty-json: 1" -H "Content-Type: application/json" \ + --data-ascii '{ + "text": "Hello App.net from curl!", + }' \ + \ + 'https://alpha-api.app.net/stream/0/posts' +~~~ diff --git a/content/docs/guides/create-an-app.md b/content/docs/guides/create-an-app.md index 0db2d96..ec25c95 100644 --- a/content/docs/guides/create-an-app.md +++ b/content/docs/guides/create-an-app.md @@ -29,7 +29,7 @@ You will be able to change all of this later, but start by giving your app a nam Enter a website that is most closely related to this app. If it doesn't make sense for you to enter a website feel free to enter in your Alpha profile URL. (https://app.net/). This will let others know who is responsible for this app. -The **Callback URL** is prefilled with http://localhost:8000 as a convenience for local development. The Callback URL will be used when you [authenticate your app](/docs/authentication/) later. +The **Callback URL** is prefilled with http://localhost:8000 as a convenience for local development. The Callback URL will be used when you [authenticate your app](/reference/authentication/) later. When you are satisfied with the information you have entered click create. @@ -47,7 +47,7 @@ You can also generate your self an access token. There are a few ways to get an access token, but the easiest way to get an access token for personal use or experimentation is to generate one from your app detail page. -To see a list of your current apps visit [account.app.net/developer/apps/](https://account.app.net/developer/apps/) +To see a list of your current apps visit [account.app.net/developer/apps/](https://account.app.net/developer/apps/). ![Your Apps Dashboard](https://files.app.net/01qlWgpd.png) @@ -59,9 +59,9 @@ From this screen, if you look at the second block you will see a link: 'Generate ![Scope Selection Screen](https://files.app.net/01qv_Geq.png) -This is the scope authorization screen. If you have already generated a token this page may have some permissions checked already otherwise there won't be any. +This is the scope authorization screen. If you have previously generated a token, some of these boxes may already be checked. -To find out more about scopes your can [read the scope docs.](/docs/authentication/#scopes) +To find out more about scopes your can [read the scope docs](/reference/authentication/#scopes). Once you have determined which scopes you will need select them in the form and then click generate. @@ -73,17 +73,26 @@ Now you should see an access token in a textbox, then you can copy and use in a Remember: An access token is just like a password. It will allow applications to interact with the API on your behalf. So, keep it secret. -## What's Next? +## Launching your app -Now that you have an access token you can use it to access authenticated parts of the API. +Before you learn more about the API and start building your app, we want to make sure you know about some other opportunities for when you're ready to launch your app. -You could: +### Directory + +We want to make sure App.net users can find all the great apps that get created so we created the [App.net Directory](https://directory.app.net/). To include your app in the directory, you must [**register your app with us**](https://alpha.app.net/developer/apps/). For more information about how the directory, please see the [Directory Requirements](https://mml.desk.com/customer/portal/articles/779115-what-are-the-criteria-for-being-accepted-into-the-app-net-directory-). -* [Send a broadcast](/docs/guides/send-a-broadcast/) -Or, you could build something completely new. Let us know what it is if you do. +### Developer Incentive Program +To financially reward the development of great apps, [we announced the Developer Incentive Program](http://blog.app.net/2012/09/27/announcing-the-app-net-developer-incentive-program/). If you'd like to include your app you must [**register for the Developer Incentive Program**](https://alpha.app.net/developer/enrollment/). +## What's Next? +Now that you have an access token you can use it to access authenticated parts of the API. +You could: + +* [Send a broadcast](/docs/guides/send-a-broadcast/) +* [Create a post](/docs/guides/create-a-post/) +Or, you could build something completely new. We always love to see new apps. diff --git a/content/docs/guides/getting-started.md b/content/docs/guides/getting-started.md new file mode 100644 index 0000000..1e0cd8c --- /dev/null +++ b/content/docs/guides/getting-started.md @@ -0,0 +1,55 @@ +--- +title: "Getting Started" +--- + +# Getting Started + +The App.net API provides lots of functionality that could be useful to implement into your app. This document provides an overview of those features so you can decide what features make sense in your app. Not all apps need to (or should) use all pieces of the App.net API. + +* TOC +{:toc} + +## API Ovierview + +App.net provides 5 major kinds of functionality. + +* Identity and Authentication + * Sign in with App.net. This can make user management much easier. +* Social graph + * Find friends from App.net. This helps solve the "cold start" problem when a user signs into your app. +* Microblogging + * Publish short public updates to App.net followers. +* Messaging + * Publish short public or private updates to any App.net user(s). +* File storage + * Store files (photos, documents, videos) with App.net. + +## Get started + +1. [Create an app](/docs/guides/create-an-app) +2. Generate a token for yourself and your new app +3. Make API requests using one of our [API Libraries](/docs/libraries). + +## Notable API features + +### Messaging + +Channels are like a chat room. They're a time ordered series of messages that can be public, private, or restricted to a group of App.net users. The messages inside of channels can take advantage of App.net files, places, and anything else the API provides. [Chat rooms](https://directory.app.net/app/145/patter/), [Broadcasts](http://blog.app.net/2013/11/21/announcing-app-net-broadcast/), and private messages are all built on top of [App.net Messaging](/docs/guides/messaging/). + +### Places + +App.net has a locations database that can be integrated with your app. This allows you to add location to Posts or Message to enable location aware apps. See the [Places reference](/docs/references/resources/places/) for more information. + +### Annotations + +Annotations are machine readable metadata that can be attached to most App.net objects (posts, messages, users, and more). They power [checkins](https://alpha.app.net/browse/checkins/), [photos](https://alpha.app.net/browse/photos/) and other rich posts on App.net. See the [Annotations introduction](/docs/references/resources/meta/annotations/) to get started. + +### Files + +App.net gives each user space to store and share files. These files can be shared publicly, attached to posts, or sent as a private message to a friend. All App.net apps share the same file storage space so if a new photo or video app comes along, you can check it out and not have to worry about migrating all your old data. See the [Files reference](/docs/references/resources/files/) for more information. + +## Where to get help + +If you find a problem with the documentation, please [open an issue](https://github.com/appdotnet/api-spec/issues) and let us know. If you have questions about the API, the quickest way to get answers is usually the [Developer Chat Room](http://patter-app.net/room.html?channel=1383) powered by the App.net API through Patter. + +During typical San Francisco business hours there are also App.net staff members available to answer questions in our [HipChat chat room](http://www.hipchat.com/garqCaGOZ). For other inquiries about account/service related issues, please email [support@app.net](mailto:support@app.net). diff --git a/content/docs/basics/messaging.md b/content/docs/guides/messaging.md similarity index 78% rename from content/docs/basics/messaging.md rename to content/docs/guides/messaging.md index 23e73e8..a2f2adf 100644 --- a/content/docs/basics/messaging.md +++ b/content/docs/guides/messaging.md @@ -7,9 +7,9 @@ title: "Messaging Overview" * TOC {:toc} -The App.net Messaging API allows a User to create public, private, semi-private messages between an arbitrary number of users. If you'd like to create public messages that your App.net followers see in their streams, you should [create a post](/docs/resources/post/lifecycle/#create-a-post) with the Stream API. If you need a more flexible messaging solution, the Messaging API is for you. +The App.net Messaging API allows a User to create public, private, semi-private messages between an arbitrary number of users. If you'd like to create public messages that your App.net followers see in their streams, you should [create a post](/reference/resources/post/lifecycle/#create-a-post) with the Stream API. If you need a more flexible messaging solution, the Messaging API is for you. -Our messaging API is built around 2 central objects: [Channels](/docs/resources/channel/) and [Messages](/docs/resources/message/). If you're familiar with the App.net Stream API, here are some analogies: +Our messaging API is built around 2 central objects: [Channels](/reference/resources/channel/) and [Messages](/reference/resources/message/). If you're familiar with the App.net Stream API, here are some analogies: * Messages are like Posts * Channels are like streams of Posts @@ -25,7 +25,7 @@ If a user is authorized to read a Channel, they can also subscribe to a channel. ## Authorization -Access to Messages in a given Channel is determined by the [ACL fields](/docs/resources/channel/#acl-fields) on the Channel itself. +Access to Messages in a given Channel is determined by the [ACL fields](/reference/resources/channel/#acl-fields) on the Channel itself. Channels can be public or private. For the purpose of access tokens, a Channel is considered public if it is readable by unauthenticated users (the `public` flag) or any authenticated ADN user (the `any_user` flag). @@ -40,11 +40,11 @@ In addition, an App access token has read access to a Channel and its contents w Users indicate their interest in a given channel by subscribing to it. When a channel is created, no one is subscribed to it. -[Private message channels](/docs/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription preferences](https://account.app.net/settings/privacy/#messaging). +[Private message channels](/reference/resources/channel/#private-message) (type `net.app.core.pm`) auto-subscribe all participants to the channel in accordance with each user's [subscription preferences](https://account.app.net/settings/privacy/#messaging). To get this same behavior for non-pm channels, you include the key `auto_subscribe: true` when you create or update the Channel. This will auto-subscribe all the users on the ACLs (according to their preferences). -If a user has [muted a channel](/docs/resources/channel/muting/#mute-a-channel) they will never be auto-subscribed to it. +If a user has [muted a channel](/reference/resources/channel/muting/#mute-a-channel) they will never be auto-subscribed to it. ## Annotations @@ -62,5 +62,5 @@ Messages, channel updates and marker updates are pushed as objects over the stre Much like annotation types, channel types are freeform strings; we suggest you use a reversed-domain format for any custom channel types. Core channel types are prefixed with `net.app.core` and may have additional validation imposed by the App.net API. Currently defined core channel types are: -* [Private Message](/docs/resources/channel/#private-message): net.app.core.pm -* [Broadcast Channel](/docs/resources/channel/#broadcast-channel): net.app.core.broadcast +* [Private Message](/reference/resources/channel/#private-message): net.app.core.pm +* [Broadcast Channel](/reference/resources/channel/#broadcast-channel): net.app.core.broadcast diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index 42e2fc3..08a5f03 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -4,11 +4,9 @@ title: "Broadcasts and the API" # Publishing Broadcasts via the API -
          -To start sending broadcasts directly from the API, you'll need an access token. If you're not familiar with how to get an access token, check out our guide on creating an app. -
          +<%= access_token_required_note %> -Broadcast Channels are designed to carry low-volume, high-value updates of interest to users. We call the actual updates themselves Broadcast Messages (or sometimes just "broadcasts"). Because broadcasts are built on top of the existing App.net [Channel](/docs/resources/channel/) and [Message](/docs/resources/message/) APIs, it's helpful to be familiar with them, but for simple tasks, there's not much you need to know. +Broadcast Channels are designed to carry low-volume, high-value updates of interest to users. We call the actual updates themselves Broadcast Messages (or sometimes just "broadcasts"). Because broadcasts are built on top of the existing App.net [Channel](/reference/resources/channel/) and [Message](/reference/resources/message/) APIs, it's helpful to be familiar with them, but for simple tasks, there's not much you need to know. Just a reminder: while you can do all of this using our API, you don't have to. We have [tools for publishers](https://broadcast.app.net/manage/) to help you quickly get started pulling content in from elsewhere on the web, and you can send them manually via the web or the App.net iOS and Android apps. To get started, **we recommend that you create and set up your broadcast channel with [our web publisher tools](https://broadcast.app.net/manage/)** and only use the API to send broadcasts via the channel you created. @@ -100,7 +98,7 @@ curl -X POST -H "Authorization: Bearer " \ You can create broadcast channels with the API as well. -Broadcast channels are created like any other channel, with a specific type value (`net.app.core.broadcast`) and a few special annotations. For information on creating channels, see the [Channel lifecycle documentation](/docs/resources/channel/lifecycle/). Broadcast channels fully support [ACLs](/docs/resources/channel/) for private applications. +Broadcast channels are created like any other channel, with a specific type value (`net.app.core.broadcast`) and a few special annotations. For information on creating channels, see the [Channel lifecycle documentation](/reference/resources/channel/lifecycle/). Broadcast channels fully support [ACLs](/reference/resources/channel/) for private applications. Here is an example channel body, set to be public, with multiple editors, which you can POST to us: diff --git a/content/docs/guides/using-annotations.md b/content/docs/guides/using-annotations.md new file mode 100644 index 0000000..cca4000 --- /dev/null +++ b/content/docs/guides/using-annotations.md @@ -0,0 +1,121 @@ +--- +title: "Using Annotations" +--- + +# Using Annotations + +* TOC +{:toc} + +Annotations are metadata that can be attached to Users, Posts, Channels, Messages, or Files. This allows developers and users to add extra information to App.net objects outside of the fields App.net has already defined. + +## What's so great about annotations? + +Annotations give developers a tremendous degree of freedom to expand upon the core functionality of App.net. They provide a way for developers to add arbitrary data to App.net objects, enabling richer content and new services. + +Let's say I'm at a restaurant eating a great dinner, but instead of just telling my followers about this restaurant I want them to be able to see a map of where it is. My Post could include geographic information about the address for the restaurant in an annotation and then clients that support this geographic annotation could show the restaurant on a map (in addition to showing my post). If the restaurant is on [OpenTable](http://www.opentable.com), I could include an annotation indicating that and my followers could see the menu and make a reservation in their own App.net client. + +## Anatomy of an annotation + +Annotations are a list of objects that have a `type` and a `value`. + +~~~ js +[ + { + "type": "com.example.awesome", + "value": { + "annotations work": "beautifully" + } + } +] +~~~ + +The `type` field identifies essentially a schema for the `value` of the annotation. Please see the [annotations reference](/reference/meta/annotations/#documenting-annotations) for more information about different kinds of annotations. + +## Example: Attach an image to a post + +When you see an image included in an App.net post, you see the results of annotations at work. We'll be using the [`net.app.core.oembed`](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.md) annotation to embed a photo in an App.net post. + +~~~ sh +curl -X POST -H "Authorization: Bearer " \ + -H "X-adn-pretty-json: 1" -H "Content-Type: application/json" \ + --data-ascii '{ + "text": "Hello App.net from curl, with a photo!", + "annotations": [ + { + "type": "net.app.core.oembed", + "value": { + "type": "photo", + "version": "1.0", + "width": 870, + "height": 106, + "url": "https://files.app.net/2jxk2CoP4", + "thumbnail_width": 200, + "thumbnail_height": 24, + "thumbnail_url": "https://files.app.net/2jxk12R7F", + "embeddable_url": "https://app.net/" + } + } + ] + }' \ + \ + 'https://alpha-api.app.net/stream/0/posts' +~~~ + +Most clients expect `thumbnail_url`, `thumbnail_width`, and `thumbnail_height` to render a preview inline with the post. + +## Example: Attach an App.net file to a post as an image + +Most apps that include images don't generate a raw oembed annotation to an image hosted somewhere else, they use the [App.net File storage](/reference/resources/files/). To do this, first you have to upload a file to App.net and then you have to create the post with an annotation as we did above. + +### Upload a file + +~~~ sh +curl -k -X POST -H "Authorization: BEARER " \ + -H "X-adn-pretty-json: 1" -F "type=testing.image" \ + -F "content=@filename.png;type=image/png" \ + 'https://alpha-api.app.net/stream/0/files' +~~~ + +This will return a JSON blob similar with the following fields we care about: + +~~~ js +{ + "data": { + "file_token": "1234567NQD4isqELTZlIiEd9fp24e5wC1NACSYFI_Svc7-hkvCKWOTsOPQLrrMiVu-9x2L400MbKlG4T8-WA97HokUdApqXwtQjJt9wOJ12ZZX_hZSFmj_O0xFlvJt8rwqaTAOvK7qECaj1LS131baLjJojErPB5TwZiQQJko0BU", + "id": "123", + ... + }, + "meta": { + "code": 200 + } +} +~~~ + +### Attach the file to a post + +Once we've uploaded the file, we can attach it to a post and let App.net generate the correct oembed annotation: + +~~~ sh +curl -X POST -H "Authorization: Bearer " \ + -H "X-adn-pretty-json: 1" -H "Content-Type: application/json" \ + --data-ascii '{ + "text": "Hello App.net from curl, with an App.net hosted photo!", + "annotations": [ + { + "type": "net.app.core.oembed", + "value": { + "+net.app.core.file": { + "file_id": "", + "file_token": "", + "format": "oembed" + } + } + } + ] + }' \ + \ + 'https://alpha-api.app.net/stream/0/posts?include_annotations=1' +~~~ + +Since annotations can contain up to [8192 bytes of data](/reference/meta/annotations/#limit), they are not returned by default. We have to explicitly request that App.net return annotations by passing the `include_annotations=1` query string parameter. diff --git a/content/docs/libraries.md b/content/docs/libraries.md new file mode 100644 index 0000000..c16e2f3 --- /dev/null +++ b/content/docs/libraries.md @@ -0,0 +1,58 @@ +--- +title: "API Libraries" +--- + +# API Libraries + +Using one of the following libraries will help you get up and running with the App.net API in no time. Most of these libraries are maintained by the community. + +* TOC +{:toc} + +## Python + + pip install adnpy + +You can view the source [on Github](https://github.com/appdotnet/adnpy) and read the [Python API docs](http://adnpy.readthedocs.org/) online. + +## Ruby + + gem install 'adn' + +Or you can add the following line to your `Gemfile` + + gem "adn" + +You can view the source [on Github](https://github.com/adn-rb/adn). + +## Javascript + +If you're creating a Node app, you can install the library with `npm` + + npm install appnet + +If you'd like to use the library as a jQuery module or view the source, check out [App.net js on Github](https://github.com/duerig/appnet.js/). + +## PHP + +You can download the latest version of [AppDotNetPHP on Github](https://github.com/jdolitsky/AppDotNetPHP). + +## Objective C + +If you're using Cocoapods, you can add the following line to your `Podfile` + + pod 'ADNKit' + +Or you can add the [ADNKit repository](https://github.com/joeldev/ADNKit) as a submodule to your project. + +If you're creating an iOS app, be sure to check out our [Login SDK](/reference/authentication/flows/sdk/) which enables users to quickly signup and login to your app. + +## Java (Android) + +Currently, our only Java library is heavily geared toward Android. Please follow [ADNLib's instructions](https://github.com/alwaysallthetime/ADNLib) to install the library. + +Be sure you also check out our [Login SDK](/reference/authentication/flows/sdk/) which enables users to quickly signup and login to your Android app. + +## Other libraries + +Our community has also released many libraries for other languages and sample code. Check them out (or add your own) on [our developer wiki](https://github.com/appdotnet/api-spec/wiki/Developer-Resources). \ No newline at end of file diff --git a/content/index.md b/content/index.md index 3f67974..2349d0e 100644 --- a/content/index.md +++ b/content/index.md @@ -15,7 +15,7 @@ This page is your starting point to getting familiar with the App.net developer
          - +

          Quick Start: Broadcast
          @@ -27,7 +27,7 @@ This page is your starting point to getting familiar with the App.net developer
          - +

          Quick Start: Authentication
          @@ -39,51 +39,26 @@ This page is your starting point to getting familiar with the App.net developer

          -### Tracking news and announcements +## Tracking news and announcements To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adnapi). You may also want to subscribe to the [App.net blog](https://broadcast.app.net/26283/appnet-blog/) for general news and [App.net API Updates](https://broadcast.app.net/24368/appnet-api-updates/) for developer related news. {::options parse_block_html="true" /}
          * (11/21/2013) **Introducing App.net Broadcast** - check out the [Send a Broadcast](/docs/guides/send-a-broadcast/) guide. -* (7/25/2013) **Introducing the Search API** — check out the documentation for [Post Search](/docs/resources/post/search/). -* (6/17/2013) **Introducing the User Stream API** — check out the documentation for [User Streams](/docs/resources/user-stream/). -* (2/5/2013) **Introducing the Place API** — check out the documentation for [Places](/docs/resources/place/). -* (1/28/2013) **Introducing the File API** — check out the documentation for [Files](/docs/resources/file/). +* (7/25/2013) **Introducing the Search API** — check out the documentation for [Post Search](/reference/resources/post/search/). +* (6/17/2013) **Introducing the User Stream API** — check out the documentation for [User Streams](/reference/resources/user-stream/). +* (2/5/2013) **Introducing the Place API** — check out the documentation for [Places](/reference/resources/place/). +* (1/28/2013) **Introducing the File API** — check out the documentation for [Files](/reference/resources/file/).
          -### Getting help and providing feedback +## Getting help and providing feedback There are numerous ways for developers to get help utilizing the platform and to provide feedback. During typical San Francisco business hours there are App.net staff members available to answer questions in our [HipChat](http://www.hipchat.com/garqCaGOZ). Developers (along with App.net staff) are often chatting in the [Developer Channel](http://patter-app.net/room.html?channel=1383). For general inquiries about account/service related issues email [support@app.net](mailto:support@app.net). For developer inquiries about the API, our Terms of Service, letting us know about something you're working on, etc., email [developers@app.net](mailto:developers@app.net). In addition to the above you can report bugs and provide feedback on the API using the [issue tracker](https://github.com/appdotnet/api-spec/issues) or by using pull requests and commit comments on the [Github repo for the API](https://github.com/appdotnet/api-spec/) or the repo for these docs. -### Terms of Service - -All usage of the App.net API is governed by our [Developer Terms of Service]( https://account.app.net/legal/developer-terms/). We spent a great deal of time making this document readable, concise, and developer friendly. Please take the time to review it. - -### Registering your app - -Establishing a robust ecosystem of great apps is critical for our success. We're always looking for more ways to promote the work of our third party developers. - -{::options parse_block_html="true" /} -
          -**If you're submitting your application to one of Apple's App Stores, we suggest you implement authentication via the [Password Flow](/docs/authentication/flows/password/) or it's possible your app will be rejected.** -
          - -#### Directory - -To make sure our members can easily find great apps [we announced the Directory](http://blog.app.net/2012/10/17/app-net-directory/). If you'd like to include your app you must [**register your app in the Directory**](https://alpha.app.net/developer/apps/). - -#### Developer Incentive Program - -To financially reward the development of great apps, [we announced the Developer Incentive Program](http://blog.app.net/2012/09/27/announcing-the-app-net-developer-incentive-program/). If you'd like to include your app you must [**register for the Developer Incentive Program**](https://alpha.app.net/developer/enrollment/). - -### Additional Resources - -Libraries, tools, code samples, blog posts and other resources to help you build great apps for the platform are featured on the [**Developer Resources**](https://github.com/appdotnet/api-spec/wiki/Developer-Resources) wiki page. Please contribute and help us make this resource better. - -#### Your hosts +## Your hosts * [Bryan Berg](http://ber.gd) ([@berg](https://alpha.app.net/berg), [bryan@app.net](mailto:bryan@app.net)) -* Mark Thurman ([@mthurman](https://alpha.app.net/mthurman), [mthurman@app.net](mthurman@app.net)) +* Mark Thurman ([@mthurman](https://alpha.app.net/mthurman), [mthurman@app.net](mailto:mthurman@app.net)) * [Alex Kessinger](http://alexkessinger.net) ([@voidfiles](https://alpha.app.net/voidfiles), [alex@app.net](mailto:alex@app.net)) * Brian Armstrong ([@barmstrong](https://alpha.app.net/barmstrong), [barmstrong@app.net](mailto:barmstrong@app.net)) diff --git a/content/docs/authentication/authorize-with-appnet.md b/content/reference/authentication/authorize-with-appnet.md similarity index 89% rename from content/docs/authentication/authorize-with-appnet.md rename to content/reference/authentication/authorize-with-appnet.md index 8208b14..e8dafd3 100644 --- a/content/docs/authentication/authorize-with-appnet.md +++ b/content/reference/authentication/authorize-with-appnet.md @@ -4,7 +4,7 @@ title: "Web Flow Integration Guide" # Web Flow Integration Guide -Now that you've identified which [web flow](/docs/authentication/flows/web/) to use with your app, it's time to expose this to end users. +Now that you've identified which [web flow](/reference/authentication/flows/web/) to use with your app, it's time to expose this to end users. * TOC {:toc} @@ -25,7 +25,7 @@ As an added benefit, this button will also allow new users to sign up for a free To implement the button on your site, you must: -1. Build [Your authentication URL](/docs/authentication/flows/web/). +1. Build [Your authentication URL](/reference/authentication/flows/web/). 1. Replace the variables inside the brackets 1. Copy and paste the snippet below into your HTML where you want the button to show up diff --git a/content/docs/authentication/flows/app-access-token.md b/content/reference/authentication/flows/app-access-token.md similarity index 100% rename from content/docs/authentication/flows/app-access-token.md rename to content/reference/authentication/flows/app-access-token.md diff --git a/content/docs/authentication/flows/password.md b/content/reference/authentication/flows/password.md similarity index 100% rename from content/docs/authentication/flows/password.md rename to content/reference/authentication/flows/password.md diff --git a/content/reference/authentication/flows/sdk.md b/content/reference/authentication/flows/sdk.md new file mode 100644 index 0000000..713c608 --- /dev/null +++ b/content/reference/authentication/flows/sdk.md @@ -0,0 +1,20 @@ +--- +title: "Authorize via App.net SDK" +--- + +# Authorize via App.net SDK + +On iOS and Android, App.net provides SDKs to streamline the process of a user authenticating your app. This is also the easiest way for a new user to sign up for App.net via their mobile device. Both SDKs work in similar ways: + +1. The developer integrates the SDK into their native app +2. The developer shows the user a "Log in" button +3. When the user taps that button, they are taken to the Official App.net App. +4. Once the user authorizes the developer's app, the Official App.net App returns the user to the developer's app with an access token. + +## iOS + +The [iOS Login SDK](https://github.com/appdotnet/ADNLogin-SDK-iOS) is hosted on Github with complete installation instructions. + +## Android + +The [Android Login SDK](https://github.com/appdotnet/ADNLogin-SDK-Android) is hosted on Github with complete installation instructions. diff --git a/content/docs/authentication/flows/web.md b/content/reference/authentication/flows/web.md similarity index 96% rename from content/docs/authentication/flows/web.md rename to content/reference/authentication/flows/web.md index 78fd43c..fb9d591 100644 --- a/content/docs/authentication/flows/web.md +++ b/content/reference/authentication/flows/web.md @@ -77,5 +77,5 @@ If you're building a client-side Javascript app or a mobile app that doesn't hav ## Finishing The Flow -After you have decided which flow will work for your app you should read our [Web Flow Integration Guide](/docs/authentication/authorize-with-appnet/) to help you integrate the authentication flow into your app. +After you have decided which flow will work for your app you should read our [Web Flow Integration Guide](/reference/authentication/authorize-with-appnet/) to help you integrate the authentication flow into your app. diff --git a/content/docs/authentication/identity-delegation.md b/content/reference/authentication/identity-delegation.md similarity index 98% rename from content/docs/authentication/identity-delegation.md rename to content/reference/authentication/identity-delegation.md index 9668e16..b7b605d 100644 --- a/content/docs/authentication/identity-delegation.md +++ b/content/reference/authentication/identity-delegation.md @@ -100,7 +100,7 @@ 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](/docs/resources/token/#retrieve-current-token) endpoint. + 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. 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`. diff --git a/content/docs/authentication/index.md b/content/reference/authentication/index.md similarity index 71% rename from content/docs/authentication/index.md rename to content/reference/authentication/index.md index 2855dcd..61aa660 100644 --- a/content/docs/authentication/index.md +++ b/content/reference/authentication/index.md @@ -23,6 +23,11 @@ It should go without saying, but for the sake of user privacy and security, plea You authenticate to our API by use of an **access token**. There are two types of access tokens: _app_ tokens and _user_ tokens. **App tokens** (referred to as "client tokens" in the [OAuth 2.0 internet-draft](http://tools.ietf.org/html/draft-ietf-oauth-v2-31)) represent access to API resources on behalf of the application and **user tokens** represent access to API resources on behalf of a specific user. Some resources are only accessible to app or user tokens. +{::options parse_block_html="true" /} +
          +**Note:** Only Apps created by a developer account can request access tokens for other App.net users. If you do not have a developer account, then your app can only be used with your own account. If you ever downgrade your developer account, all current tokens for your app will still work but no new users will be able to authorize it. +
          + ## How do I get an access token? {::options parse_block_html="true" /} @@ -32,11 +37,17 @@ You authenticate to our API by use of an **access token**. There are two types o **To obtain a user token**, you must use one of these flows: -* **[Web flow (server-side)](/docs/authentication/flows/web/#server-side-flow)** - use this if you're building a web application backed by a server. (The OAuth 2.0 internet-draft calls this the [Authorization Code Flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1).) -* **[Web flow (client-side)](/docs/authentication/flows/web/#client-side-flow)** - use this if you're building an application without a central server, like a mobile app or a client-side Javascript app. (The OAuth 2.0 internet-draft calls this the [Implicit Grant Flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.2).) -* **[Password flow](/docs/authentication/flows/password/)** - use this if you're building a native application (or an application where it is difficult to use a web browser) and want to avoid implementing a web-based authentication flow. This flow requires special permission to use and comes with a bunch of extra rules and requirements to protect user security. +* **[Web flow (server-side)](/reference/authentication/flows/web/#server-side-flow)** - use this if you're building a web application backed by a server. (The OAuth 2.0 internet-draft calls this the [Authorization Code Flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1).) +* **[Web flow (client-side)](/reference/authentication/flows/web/#client-side-flow)** - use this if you're building an application without a central server, like a mobile app or a client-side Javascript app. (The OAuth 2.0 internet-draft calls this the [Implicit Grant Flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.2).) +* **[Native App SDK flow](/reference/authentication/flows/sdk/)** - use this if you're building an iOS or Android client. We provide an SDK that you can integrate into your app to streamline authentication. +* **[Password flow](/reference/authentication/flows/password/)** - use this if you're building a native application (or an application where it is difficult to use a web browser) and want to avoid implementing a web-based authentication flow. This flow requires special permission to use and comes with a bunch of extra rules and requirements to protect user security. + +{::options parse_block_html="true" /} +
          +**If you're submitting your application to one of Apple's App Stores, we suggest you implement authentication via the [Native App SDK flow](/reference/authentication/flows/sdk/) or it's possible your app will be rejected.** +
          -**To obtain an app token**, you must use the **[app access token flow](/docs/authentication/flows/app-access-token)**. (The OAuth 2.0 internet-draft calls this this [Client Credentials Grant](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.4).) +**To obtain an app token**, you must use the **[app access token flow](/reference/authentication/flows/app-access-token)**. (The OAuth 2.0 internet-draft calls this this [Client Credentials Grant](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.4).) We also intend to provide a SDK you can embed into your mobile applications to provide seamless authentication with App.net to your application's users. @@ -111,10 +122,10 @@ When making a call to one of our API resources, there are three ways to include Each endpoint specified the kind of token it needs: * None: no access token is required -* User: a [user token](/docs/authentication/#how-do-i-get-an-access-token) is required. -* App: an [app token](/docs/authentication/flows/app-access-token/) is required. +* User: a [user token](/reference/authentication/#how-do-i-get-an-access-token) is required. +* App: an [app token](/reference/authentication/flows/app-access-token/) is required. * Any: either a user token or an app token may be provided but you must have a token of some kind. -* Varies: Authentication may not be required but if it is not provided, you may not be allowed to see a specific resource. For instance, the [Retrieve a Channel](/docs/resources/channel/lookup/#retrieve-a-channel) endpoint allows unauthenticated calls. But if you try to retrieve a Channel that is not marked public, the call will fail. +* Varies: Authentication may not be required but if it is not provided, you may not be allowed to see a specific resource. For instance, the [Retrieve a Channel](/reference/resources/channel/lookup/#retrieve-a-channel) endpoint allows unauthenticated calls. But if you try to retrieve a Channel that is not marked public, the call will fail. ## How can I authenticate between App.net apps? diff --git a/content/reference/index.md b/content/reference/index.md new file mode 100644 index 0000000..b490703 --- /dev/null +++ b/content/reference/index.md @@ -0,0 +1,6 @@ +--- +title: "API Reference" +--- +# API Reference + +These pages contain the complete specification of how the App.net API works. We try to follow standard practices to make our API easy to use from one of our [client libraries](/docs/libraries/) or from any normal HTTP client. We use standard HTTP headers to [authorize your use of the API](/reference/authentication/) and to [rate limit requests](/reference/make-request/rate-limits/). Our [API responses](/reference/make-request/responses/) are always JSON encoded and use appropriate [HTTP error codes](/reference/make-request/responses/#possible-http-status-codes) to signify an API failure. Once you're familiar with the building blocks of our API, we encourage you to explore the different [resources](/reference/resources/) for detailed documentation. \ No newline at end of file diff --git a/content/docs/basics/data-formats.md b/content/reference/make-request/data-formats.md similarity index 100% rename from content/docs/basics/data-formats.md rename to content/reference/make-request/data-formats.md diff --git a/content/docs/basics/migrations.md b/content/reference/make-request/migrations.md similarity index 100% rename from content/docs/basics/migrations.md rename to content/reference/make-request/migrations.md diff --git a/content/docs/basics/pagination.md b/content/reference/make-request/pagination.md similarity index 85% rename from content/docs/basics/pagination.md rename to content/reference/make-request/pagination.md index ee3290a..adfaf9a 100644 --- a/content/docs/basics/pagination.md +++ b/content/reference/make-request/pagination.md @@ -46,11 +46,11 @@ Requests for paginated streams can optionally be filtered by passing the followi since_id - Return objects following the max_id provided in the response metadata of a previous query or following one of the special pagination ids for streams with Stream Markers. + Return objects following the max_id provided in the response metadata of a previous query or following one of the special pagination ids for streams with Stream Markers. before_id - Return objects preceding the min_id provided in the response metadata of a previous query or preceding one of the special pagination ids for streams with Stream Markers. + Return objects preceding the min_id provided in the response metadata of a previous query or preceding one of the special pagination ids for streams with Stream Markers. count @@ -61,7 +61,7 @@ Requests for paginated streams can optionally be filtered by passing the followi ### Special pagination ids -When requesting objects from an endpoint that supports [Stream Markers](/docs/resources/stream-marker), you can pass the following special values to the `since_id` and `before_id` pagination parameters: +When requesting objects from an endpoint that supports [Stream Markers](/reference/resources/stream-marker), you can pass the following special values to the `since_id` and `before_id` pagination parameters: @@ -73,26 +73,26 @@ When requesting objects from an endpoint that supports [Stream Markers](/docs/re - + - + - + - +
          last_readUse the last_read_id of the current Stream Marker (if there is one) as the value.Use the last_read_id of the current Stream Marker (if there is one) as the value.
          last_read_inclusiveUse the last_read_id of the current Stream Marker (if there is one) as the value. Also include the "last read" object.Use the last_read_id of the current Stream Marker (if there is one) as the value. Also include the "last read" object.
          markerUse the id of the current Stream Marker (if there is one) as the value.Use the id of the current Stream Marker (if there is one) as the value.
          marker_inclusiveUse the id of the current Stream Marker (if there is one) as the value. Also include the "marked" object.Use the id of the current Stream Marker (if there is one) as the value. Also include the "marked" object.
          ## Response Metadata -Responses from paginated streams will include the following fields in the `meta` object of the [response envelope](/docs/basics/responses/#response-envelope). +Responses from paginated streams will include the following fields in the `meta` object of the [response envelope](/reference/make-request/responses/#response-envelope). diff --git a/content/docs/basics/rate-limits.md b/content/reference/make-request/rate-limits.md similarity index 100% rename from content/docs/basics/rate-limits.md rename to content/reference/make-request/rate-limits.md diff --git a/content/docs/basics/responses.md b/content/reference/make-request/responses.md similarity index 78% rename from content/docs/basics/responses.md rename to content/reference/make-request/responses.md index 919d9e9..d4cf781 100644 --- a/content/docs/basics/responses.md +++ b/content/reference/make-request/responses.md @@ -7,9 +7,9 @@ title: "Responses" * TOC {:toc} -All responses to requests to the App.net API endpoints listed under [Resources](/docs/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. +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](/docs/authentication) return a slightly different format that follows the OAuth2 specification.* +*Please note: the [authentication endpoints](/reference/authentication) return a slightly different format that follows the OAuth2 specification.* {::options parse_block_html="true" /} @@ -17,7 +17,7 @@ All responses to requests to the App.net API endpoints listed under [Resources]( The top-level response is an object containing two keys. The first key, ```data```, corresponds to the actual response item requested. This may either be an object itself or a list of objects. The particular data returned is described in each endpoint's documentation. If the request is unsuccessful (results in an error), no ```data``` key will be present. -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 metadata](/docs/basics/pagination/#response-metadata) and/or a [stream marker](/docs/resources/stream-marker/) when relevant. +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 metadata](/reference/make-request/pagination/#response-metadata) and/or a [stream marker](/reference/resources/stream-marker/) when relevant. ### Sample Response Envelope ~~~ js @@ -103,12 +103,12 @@ If the request was unsuccessful for some reason, no ```data``` key will be retur - + - + @@ -136,7 +136,7 @@ App.net uses the HTTP status code to indicate if an API request was a success or - + @@ -144,11 +144,11 @@ App.net uses the HTTP status code to indicate if an API request was a success or - + - + @@ -160,7 +160,7 @@ App.net uses the HTTP status code to indicate if an API request was a success or - + @@ -168,7 +168,7 @@ App.net uses the HTTP status code to indicate if an API request was a success or - +
          code-usedaccess_tokenaccess_token The passed OAuth code was already used to generate a token.
          redirect-uri-requiredaccess_tokenaccess_token The call to access_token must include redirect_uri.
          302 FoundRedirection to the final destination of a resource. Returned when retrieving file contents, user avatar, or a cover image.Redirection to the final destination of a resource. Returned when retrieving file contents, user avatar, or a cover image.
          400 Bad Request
          401 UnauthorizedA token is required. If you passed a token, a message should indicate why this token is not authorized. The error slugs should also provide a reason why this token is invalid.A token is required. If you passed a token, a message should indicate why this token is not authorized. The error slugs should also provide a reason why this token is invalid.
          403 ForbiddenThe token you are providing doesn't have the right to perform the request. Please check that your token is of the correct type and has the required scope.The token you are providing doesn't have the right to perform the request. Please check that your token is of the correct type and has the required scope.
          404 Not Found
          429 Too Many RequestsThe request could not be completed due to a rate limit. Please wait at the number of seconds specified in the Retry-After header before you retry this request.The request could not be completed due to a rate limit. Please wait at the number of seconds specified in the Retry-After header before you retry this request.
          500 Internal Server Error
          507 Insufficient StorageThe request couldn't be completed because the authorized user has hit a quota limit. This could be returned when trying to upload a file or when a user on a free account tried to follow more users than their plan allows. The data.limits and data.storage attributes of the current token information can help an app avoid this error.The request couldn't be completed because the authorized user has hit a quota limit. This could be returned when trying to upload a file or when a user on a free account tried to follow more users than their plan allows. The data.limits and data.storage attributes of the current token information can help an app avoid this error.
          diff --git a/content/docs/meta/annotations.md b/content/reference/meta/annotations.md similarity index 68% rename from content/docs/meta/annotations.md rename to content/reference/meta/annotations.md index c4571f9..91979ae 100644 --- a/content/docs/meta/annotations.md +++ b/content/reference/meta/annotations.md @@ -7,29 +7,16 @@ title: "Annotations" * TOC {:toc} -Annotations are metadata that can be attached to Users, Posts, Channels, Messages, or Files. This allows developers and users to add extra information to App.net objects outside of the fields App.net has already defined. -## What's so great about annotations? - -Annotations give developers a tremendous degree of freedom to expand upon the core functionality of App.net. They provide a way for developers to add arbitrary data to App.net objects, enabling richer content and new services. - -Let's say I'm at a restaurant eating a great dinner, but instead of just telling my followers about this restaurant I want them to be able to see a map of where it is. My Post could include geographic information about the address for the restaurant in an annotation and then clients that support this geographic annotation could show the restaurant on a map (in addition to showing my post). If the restaurant is on [OpenTable](http://www.opentable.com), I could include an annotation indicating that and my followers could see the menu and make a reservation in their own App.net client. - -## Developing with annotations - -### Anatomy of an annotation - -In general, annotations are a list of objects that have a ```type``` and a ```value```. +## Annotation Fields ~~~ js -[ - { - "type": "com.example.awesome", - "value": { - "annotations work": "beautifully" - } +{ + "type": "com.example.awesome", + "value": { + "annotations work": "beautifully" } -] +} ~~~ @@ -50,46 +37,7 @@ In general, annotations are a list of objects that have a ```type``` and a ```va
          -### Annotations in App.net objects - -All objects that support annotations (User, Post, Channel, Message, File) have an `annotations` field which will contain a list of individual annotation objects if they are present. - -#### Example: annotations field in a Post - -~~~ js -{ - "annotations": [ - { - "type": "com.example.awesome", - "value": { - "annotations work": "beautifully" - } - } - ], - "created_at": "2012-08-30T23:30:14Z", - "entities": { - "hashtags": [], - "links": [], - "mentions": [] - }, - "html": "first annotation post", - "id": "1", - "num_replies": 0, - "num_reposts": 0, - "num_stars": 0, - "source": { - "link": "https://join.app.net/", - "name": "App.net" - }, - "text": "first annotation post", - "thread_id": "1255", - "user": {...}, - "you_reposted": false, - "you_starred": false -} -~~~ - -### Limits +## Limits - Each object (User, Post, Channel, Message, File) is allowed at most 8192 bytes worth of annotations (in total, when serialized as JSON). - Post and Message annotations are immutable and can only be added at creation time. @@ -99,21 +47,21 @@ All objects that support annotations (User, Post, Channel, Message, File) have a - User annotations are meant to provide more information about the user. **They are not meant to be an arbitrary data store for apps**. - Some annotations are read-only and will be ignored or rejected if you try to write to them. -### Creating, Updating and Deleting +## Creating, Updating and Deleting -For Posts, Messages, Channels, and Files, you can create annotations when you create the object. You must pass JSON objects that include annotations matching the above schema. Please see the documentation for [creating Posts](/docs/resources/post/lifecycle/#create-a-post), [Messages](/docs/resources/message/lifecycle/#create-a-message), [Channels](/docs/resources/channel/lifecycle/#create-a-channel), or [Files](/docs/resources/file/lifecycle/#create-a-file). +For Posts, Messages, Channels, and Files, you can create annotations when you create the object. You must pass JSON objects that include annotations matching the above schema. Please see the documentation for [creating Posts](/reference/resources/post/lifecycle/#create-a-post), [Messages](/reference/resources/message/lifecycle/#create-a-message), [Channels](/reference/resources/channel/lifecycle/#create-a-channel), or [Files](/reference/resources/file/lifecycle/#create-a-file). -To add or update User or Channel annotations, you [update a User's profile](/docs/resources/user/profile/#update-a-user), [update a Channel](/docs/resources/channel/lifecycle/#update-a-channel), or [update a File](/docs/resources/file/lifecycle/#update-a-file) and pass in the annotations you want to add or update. To delete an annotation, omit the `value` key for the annotation type you want to delete. For example, to delete a user's blog url, specify `{"type": "net.app.core.directory.blog"}`. +To add or update User or Channel annotations, you [update a User's profile](/reference/resources/user/profile/#update-a-user), [update a Channel](/reference/resources/channel/lifecycle/#update-a-channel), or [update a File](/reference/resources/file/lifecycle/#update-a-file) and pass in the annotations you want to add or update. To delete an annotation, omit the `value` key for the annotation type you want to delete. For example, to delete a user's blog url, specify `{"type": "net.app.core.directory.blog"}`. -### Retrieving +## Retrieving Since annotations can be up to 8192 bytes, they are never included by default. When making a request for Users, Posts, Channels, Messages, or Files, you can use the parameter `include_annotations=1` to receive all applicable annotations. When requesting Users or Posts you can use `include_user_annotations=1` or `include_post_annotations=1` to include just those annotations. When requesting Channels or Messages you can use `include_channel_annotations=1` or `include_message_annotations=1` to include just those annotations. When requesting Files you can use `include_file_annotations=1` or `include_user_annotations=1` to include just those annotations. -### Displaying +## Displaying You are free to choose if and how you render annotations. **Be very careful when consuming this data and do not assume that it follows a specific schema.** Treat data in annotations as untrusted data. Program defensively: your app should not crash or otherwise throw an error if it receives a string where there is usually a dictionary, etc. -### Namespaces +## Namespaces App.net will coordinate with the community to define schemas for common annotation formats. They will live under the `net.app.core.*` namespace. This is the only restricted annotation namespace for the `type` field. Any annotation in this namespace must be validated by the API against a [published schema](#core-annotations). Outside of this namespace, developers should create annotations in either the `net.app.[username]` namespace or a reversed-domain namespace of their choosing. @@ -121,7 +69,7 @@ In the `value` of any annotation (including non-core annotations), we treat any ## Documenting annotations -To foster collaboration and adoption, we've set up a [github repository](https://github.com/appdotnet/object-metadata) for documenting annotations. To discuss annotations, please use the associate [issue tracker](https://github.com/appdotnet/object-metadata/issues). For more information on submitting / updating documentation please review the [README](https://github.com/appdotnet/object-metadata). +To foster collaboration and adoption, we've set up a [github repository](https://github.com/appdotnet/object-metadata) for documenting annotations. To discuss annotations, please use the associate [issue tracker](https://github.com/appdotnet/object-metadata/issues). For more information on submitting / updating documentation please review the [README](https://github.com/appdotnet/object-metadata). ### Core annotations @@ -131,10 +79,10 @@ We currently define the following core annotations: | Name | Type | Description | | ---- | ---- | ----------- | -| [Attachments](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.attachments.md) | net.app.core.attachments | A pointer to App.net [Files](/docs/resources/file/) that are attached to the object being annotated. | -| [Channel Invite](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.channel.invite.md) | net.app.core.channel.invite | A pointer to a [Channel](/docs/resources/channel/). | -| [Checkin](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.checkin.md) | net.app.core.checkin | Indicates a user has "checked in" to a [Place](/docs/resources/place/). | -| [Phototag](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.phototag.md) | net.app.core.phototag | Indicates a user appears in a photo | +| [Attachments](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.attachments.md) | net.app.core.attachments | A pointer to App.net [Files](/reference/resources/file/) that are attached to the object being annotated. | +| [Channel Invite](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.channel.invite.md) | net.app.core.channel.invite | A pointer to a [Channel](/reference/resources/channel/). | +| [Checkin](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.checkin.md) | net.app.core.checkin | Indicates a user has "checked in" to a [Place](/reference/resources/place/). | +| [Phototag](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.phototag.md) | net.app.core.phototag | Indicates a user appears in a photo | | [Crosspost](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.crosspost.md) | net.app.core.crosspost | Specifies the original or canonical source of a Post on App.net from somewhere else on the web. | | [Blog URL](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.directory.blog.md) | net.app.core.directory.blog | A pointer to a user's blog. | | [Facebook ID](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.directory.facebook.md) | net.app.core.directory.facebook | A pointer to a user's Facebook account. | @@ -147,17 +95,11 @@ We currently define the following core annotations: | [oEmbed Metadata](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.oembed.metadata.md) | net.app.core.oembed.metadata | Provides information for generating an oEmbed representation of a file. | {: .table .table-striped} -We have considered core annotations for the following types of data: - -* Long-form content -* Attribution and source -* Additional content license grants, where users can opt in to Creative Commons licensing, etc., if desired. - -If you are interested in these ideas, please [open an issue](https://github.com/appdotnet/object-metadata/issues). +If you are interested in proposing another annotation, please [open an issue](https://github.com/appdotnet/object-metadata/issues). Developers are encouraged to create annotations for data not well represented here. If possible, care should be taken not to overlap with existing annotations. Annotations designed to address edge-cases in well-known annotations should include both the well-known annotation and only the augmented parts in the enhancing annotation. -### Annotation replacement values +## Replacement values When App.net processes annotation values, any value with a key that starts with `+net.app.core.*` will be rewritten based on the core schemas defined below. For example, when attaching a File to a Post, you might send App.net the following annotation: @@ -194,8 +136,8 @@ We currently define the following replacement values in annotations: | Name | Key | Description | | ---- | --- | ----------- | -| [File](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file.md) | +net.app.core.file | Add information about an App.net [File](/docs/resources/file/) to an annotation. | -| [File List](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file_list.md) | +net.app.core.file_list | Add information about a list of App.net [Files](/docs/resources/file/) to an annotation. | -| [Place](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.place.md) | +net.app.core.place | Add information about a [Place](/docs/resources/place/) to an annotation. | -| [User](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.user.md) | +net.app.core.user | Add information about a [User](/docs/resources/user/) to an annotation. | +| [File](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file.md) | +net.app.core.file | Add information about an App.net [File](/reference/resources/file/) to an annotation. | +| [File List](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.file_list.md) | +net.app.core.file_list | Add information about a list of App.net [Files](/reference/resources/file/) to an annotation. | +| [Place](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.place.md) | +net.app.core.place | Add information about a [Place](/reference/resources/place/) to an annotation. | +| [User](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.user.md) | +net.app.core.user | Add information about a [User](/reference/resources/user/) to an annotation. | {: .table .table-striped} diff --git a/content/docs/meta/entities.md b/content/reference/meta/entities.md similarity index 95% rename from content/docs/meta/entities.md rename to content/reference/meta/entities.md index 64c8299..214ec56 100644 --- a/content/docs/meta/entities.md +++ b/content/reference/meta/entities.md @@ -61,7 +61,7 @@ Bring another user's attention to your post. A mention starts with @ is_leading boolean - Is this mention a leading mention? A leading mention is a mention at the beginning of a post's text. This is used when computing the whether the post is a directed post. + Is this mention a leading mention? A leading mention is a mention at the beginning of a post's text. This is used when computing the whether the post is a directed post. @@ -182,7 +182,7 @@ Entities are automatically extracted from the post text but there are 2 cases wh ### Mentions in machine only posts -[Machine only Posts](/docs/resources/post/#machine-only-posts) don't have any text so entities cannot be extracted. We allow you to specify up to 10 users (by username or id) who can be mentioned in a machine only post. A machine only post with mentions is treated as a directed post to those users. You should not pass the ```pos``` or ```len``` keys in these mentions. Please see the example: +[Machine only Posts](/reference/resources/post/#machine-only-posts) don't have any text so entities cannot be extracted. We allow you to specify up to 10 users (by username or id) who can be mentioned in a machine only post. A machine only post with mentions is treated as a directed post to those users. You should not pass the ```pos``` or ```len``` keys in these mentions. Please see the example: ~~~ js { diff --git a/content/docs/other/feeds.md b/content/reference/other/feeds.md similarity index 91% rename from content/docs/other/feeds.md rename to content/reference/other/feeds.md index aafa2c4..69e56da 100644 --- a/content/docs/other/feeds.md +++ b/content/reference/other/feeds.md @@ -13,8 +13,8 @@ Feeds describe our system for simple syndication of public posts on App.net. We There are 2 different kinds of feeds, but they all follow the same pattern: -* Users Post feed: A feed for a single User's public posts on App.net. This is a feed version of the [Retrieve Posts created by a User](/docs/resources/post/streams/#retrieve-posts-created-by-a-user) endpoint. -* Hashtag feed: A feed containing all public Posts that are tagged with a specific hashtag. This is a feed version of the [Retrieve tagged Posts](/docs/resources/post/streams/#retrieve-tagged-posts) endpoint. +* Users Post feed: A feed for a single User's public posts on App.net. This is a feed version of the [Retrieve Posts created by a User](/reference/resources/post/streams/#retrieve-posts-created-by-a-user) endpoint. +* Hashtag feed: A feed containing all public Posts that are tagged with a specific hashtag. This is a feed version of the [Retrieve tagged Posts](/reference/resources/post/streams/#retrieve-tagged-posts) endpoint. We intend to support more feed formats and richer support for filters in the near future. @@ -30,7 +30,7 @@ All responses are returned as RSS. We are following the spec for RSS 2.0 as desc ## Retrieve a feed for a User -Retrieve a feed for the User [@voidfiles](http://alpha.app.net/voidfiles). This endpoint is similar to the [Retrieve Posts created by a User](/docs/resources/post/streams/#retrieve-posts-created-by-a-user) endpoint. +Retrieve a feed for the User [@voidfiles](http://alpha.app.net/voidfiles). This endpoint is similar to the [Retrieve Posts created by a User](/reference/resources/post/streams/#retrieve-posts-created-by-a-user) endpoint. ### URL > https://alpha-api.app.net/feed/rss/users/@username/posts @@ -68,7 +68,7 @@ Retrieve a feed for the User [@voidfiles](http://alpha.app.net/voidfiles). This ## Retrieve a feed for a hashtag -Retrieve a feed for the specified hashtag. This endpoint is similar to the [Retrieve tagged Posts](/docs/resources/post/streams/#retrieve-tagged-posts) endpoint. +Retrieve a feed for the specified hashtag. This endpoint is similar to the [Retrieve tagged Posts](/reference/resources/post/streams/#retrieve-tagged-posts) endpoint. ### URL > https://alpha-api.app.net/feed/rss/posts/tag/hashtag diff --git a/content/docs/other/oembed.md b/content/reference/other/oembed.md similarity index 100% rename from content/docs/other/oembed.md rename to content/reference/other/oembed.md diff --git a/content/docs/other/web-intents.md b/content/reference/other/web-intents.md similarity index 100% rename from content/docs/other/web-intents.md rename to content/reference/other/web-intents.md diff --git a/content/docs/resources/app-stream/index.md b/content/reference/resources/app-stream/index.md similarity index 90% rename from content/docs/resources/app-stream/index.md rename to content/reference/resources/app-stream/index.md index 40e6474..78d2cfe 100644 --- a/content/docs/resources/app-stream/index.md +++ b/content/reference/resources/app-stream/index.md @@ -84,17 +84,17 @@ A customized view of the global events happening on App.net that is streamed to curl -i -An App Stream contains all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/docs/authentication/flows/app-access-token/)**. You can create up to 5 app streams per App token. An App Stream can only be used on a server (where the App token can be kept secret). If you would like your stream to be automatically deleted when you disconnect from your app stream, add the `auto_delete=1` query string parameter when connecting to a stream. +An App Stream contains all public activity (and any private activity the App is authorized to see). **It must be accessed with an [App access token](/reference/authentication/flows/app-access-token/)**. You can create up to 5 app streams per App token. An App Stream can only be used on a server (where the App token can be kept secret). If you would like your stream to be automatically deleted when you disconnect from your app stream, add the `auto_delete=1` query string parameter when connecting to a stream. -Each object in the App Stream will be formatted in a [response envelope](/docs/basics/responses/#response-envelope). The ```data``` key will always contain the object. Some actions (like following a user) will contain extra information in the ```meta``` key. +Each object in the App Stream will be formatted in a [response envelope](/reference/make-request/responses/#response-envelope). The ```data``` key will always contain the object. Some actions (like following a user) will contain extra information in the ```meta``` key. -If you would like a realtime stream of an individual user's view of App.net, please use a [User Stream](/docs/resources/user-stream). +If you would like a realtime stream of an individual user's view of App.net, please use a [User Stream](/reference/resources/user-stream). Since memory and bandwidth is not unlimited, each Stream has associated limits. App.net maintains a buffer of objects to send to a client, but if that buffer fills, your Stream will be disconnected. Please ensure that you are only requesting streams of data that you can actually process. ## Filters -Streams will give you lots of data, much of which your application may not want. A [Filter](/docs/resources/filter/) can be passed to the [stream creation endpoint](/docs/resources/app-stream/lifecycle/#create-a-stream) to control what objects are actually delivered to your App by our servers. +Streams will give you lots of data, much of which your application may not want. A [Filter](/reference/resources/filter/) can be passed to the [stream creation endpoint](/reference/resources/app-stream/lifecycle/#create-a-stream) to control what objects are actually delivered to your App by our servers. ## Response Format @@ -111,7 +111,7 @@ The Stream contains frames separated by ```\r\n```. For example: ### Data Message -A data message is a JSON object that represents an action that was taken in the App.net API. These messages are returned in a [response envelope](/docs/basics/responses/#response-envelope). The `data` that's returned is meant to match the responses from the polling API endpoints as closely as possible. Please look at the [sample stream objects](#sample-stream-objects) for documentation about each kind of data message. +A data message is a JSON object that represents an action that was taken in the App.net API. These messages are returned in a [response envelope](/reference/make-request/responses/#response-envelope). The `data` that's returned is meant to match the responses from the polling API endpoints as closely as possible. Please look at the [sample stream objects](#sample-stream-objects) for documentation about each kind of data message. The `meta` object may contain the following standard keys: @@ -199,7 +199,7 @@ as a key in the object so it is easy to distinguish from a Post. ## Notifications -One of the main uses of an App Stream is to send notifications to users about what is happening on App.net. When you run a notification service, you need to respect a user's [muting](/docs/resources/user/muting/) and [blocking](/docs/resources/user/blocking/) preferences and whether that event came from a [bot account](/docs/resources/user/#user-fields). If you're sending ["standard" notifications](#standard-notifications), App.net provides some information with each streaming event to make this easier. If you'd like to do something besides the standard notifications, App.net provides some [advanced guidance](#advanced-notifications). +One of the main uses of an App Stream is to send notifications to users about what is happening on App.net. When you run a notification service, you need to respect a user's [muting](/reference/resources/user/muting/) and [blocking](/reference/resources/user/blocking/) preferences and whether that event came from a [bot account](/reference/resources/user/#user-fields). If you're sending ["standard" notifications](#standard-notifications), App.net provides some information with each streaming event to make this easier. If you'd like to do something besides the standard notifications, App.net provides some [advanced guidance](#advanced-notifications). ### Standard Notifications @@ -228,10 +228,10 @@ In general, clients that send push notifications should send based on the follow ### Advanced Notifications -If you'd like to do complex notifications that aren't possible with the [standard notifications](#standard-notifications), your notification server will still need to respect a user's [muting](/docs/resources/user/muting/) and [blocking](/docs/resources/user/blocking/) preferences. +If you'd like to do complex notifications that aren't possible with the [standard notifications](#standard-notifications), your notification server will still need to respect a user's [muting](/reference/resources/user/muting/) and [blocking](/reference/resources/user/blocking/) preferences. -1. When your notification server starts, retrieve and store the list of [users who have authorized your app](/docs/resources/token/#retrieve-authorized-user-ids-for-an-app). -2. For each of those users, retrieve and store the users they have [muted](/docs/resources/user/muting/#retrieve-muted-user-ids-for-multiple-users) and [blocked](/docs/resources/user/blocking/#retrieve-blocked-user-ids-for-multiple-users). +1. When your notification server starts, retrieve and store the list of [users who have authorized your app](/reference/resources/token/#retrieve-authorized-user-ids-for-an-app). +2. For each of those users, retrieve and store the users they have [muted](/reference/resources/user/muting/#retrieve-muted-user-ids-for-multiple-users) and [blocked](/reference/resources/user/blocking/#retrieve-blocked-user-ids-for-multiple-users). 3. As you process [(un)mutes](#mute) and [(un)blocks](#block) from the Streaming API, update those lists for each user. 4. Before you send a notification to a user, check that it didn't come from a user that they have muted or blocked. Also, check to make sure `meta.suppress_notifications_all` is not `true`. diff --git a/content/docs/resources/app-stream/lifecycle.md b/content/reference/resources/app-stream/lifecycle.md similarity index 77% rename from content/docs/resources/app-stream/lifecycle.md rename to content/reference/resources/app-stream/lifecycle.md index f8422db..384c14a 100644 --- a/content/docs/resources/app-stream/lifecycle.md +++ b/content/reference/resources/app-stream/lifecycle.md @@ -9,9 +9,9 @@ title: "App Stream Lifecycle" ## Create a Stream -Create a [Stream](/docs/resources/app-stream/) for the current token. +Create a [Stream](/reference/resources/app-stream/) for the current token. -Send a JSON document that matches the [stream schema](/docs/resources/app-stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. +Send a JSON document that matches the [stream schema](/reference/resources/app-stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. You can create up to 5 streams per App token. @@ -19,7 +19,7 @@ You can create up to 5 streams per App token. #### POST Data -A JSON object representing the stream to create. See [the stream object](/docs/resources/app-stream/) for more information. Specify ```filter_id``` instead of ```filter``` if you want to filter this stream. (Omit the ```id``` and ```endpoint``` parameters). +A JSON object representing the stream to create. See [the stream object](/reference/resources/app-stream/) for more information. Specify ```filter_id``` instead of ```filter``` if you want to filter this stream. (Omit the ```id``` and ```endpoint``` parameters). #### Example @@ -61,7 +61,7 @@ A JSON object representing the stream to create. See [the stream object](/docs/r ## Retrieve a Stream -Returns a specific [Stream](/docs/resources/app-stream/) object. +Returns a specific [Stream](/reference/resources/app-stream/) object. <%= endpoint "GET", "streams/[stream_id]", "App" %> @@ -104,7 +104,7 @@ Returns a specific [Stream](/docs/resources/app-stream/) object. ## Get current token's Streams -Return the [Streams](/docs/resources/app-stream/) for the current token. +Return the [Streams](/reference/resources/app-stream/) for the current token. <%= endpoint "GET", "streams", "App" %> @@ -154,7 +154,7 @@ Return the [Streams](/docs/resources/app-stream/) for the current token. ## Update a Stream -Update a [Stream](/docs/resources/app-stream/). You can update a Stream by PUTing a JSON document that matches the [stream schema](/docs/resources/app-stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. +Update a [Stream](/reference/resources/app-stream/). You can update a Stream by PUTing a JSON document that matches the [stream schema](/reference/resources/app-stream/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```object_types```, ```type```, ```filter_id``` and ```key```. If you don't want to specify a filter, omit ```filter_id```. If you don't want to specify a key, omit ```key```. <%= endpoint "PUT", "streams/[stream_id]", "App" %> @@ -203,11 +203,11 @@ Update a [Stream](/docs/resources/app-stream/). You can update a Stream by PUTin ## Delete a Stream -Delete a [Stream](/docs/resources/app-stream/). The Stream must belong to the current User. It returns the deleted Stream on success. +Delete a [Stream](/reference/resources/app-stream/). The Stream must belong to the current User. It returns the deleted Stream on success. -If you'd like your app stream to be automatically deleted when you disconnect from it, please add the [`auto_delete=1`](/docs/resources/user-stream/#limits) query string parameter when you connect to your app stream. +If you'd like your app stream to be automatically deleted when you disconnect from it, please add the [`auto_delete=1`](/reference/resources/user-stream/#limits) query string parameter when you connect to your app stream. -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "streams/[stream_id]", "App" %> @@ -250,9 +250,9 @@ If you'd like your app stream to be automatically deleted when you disconnect fr ## Delete all of the current user's Streams -Delete all [Streams](/docs/resources/app-stream/) for the current token. It returns the deleted Streams on success. +Delete all [Streams](/reference/resources/app-stream/) for the current token. It returns the deleted Streams on success. -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "streams", "App" %> diff --git a/content/docs/resources/channel/index.md b/content/reference/resources/channel/index.md similarity index 63% rename from content/docs/resources/channel/index.md rename to content/reference/resources/channel/index.md index bba128f..dfba491 100644 --- a/content/docs/resources/channel/index.md +++ b/content/reference/resources/channel/index.md @@ -9,7 +9,7 @@ title: "Channel" * TOC {:toc} -A Channel is a user created stream of Messages. It controls access to the messages in the channel allowing for (among other things) public, private, and group messaging. For an overview of the App.net messaging API, please see the [Introduction to App.net Messaging](/docs/basics/messaging/). +A Channel is a user created stream of Messages. It controls access to the messages in the channel allowing for (among other things) public, private, and group messaging. For an overview of the App.net messaging API, please see the [Introduction to App.net Messaging](/docs/guides/messaging/). ## Example Channel object @@ -42,12 +42,12 @@ end %> messages integer - The number of Messages in the channel. + The number of Messages in the channel. subscribers integer - The number of Users subscribed to this channel. This field is only shown to channel editors. + The number of Users subscribed to this channel. This field is only shown to channel editors. @@ -64,18 +64,18 @@ end %> owner - User object - This is an embedded version of the User object. In certain cases (e.g., when a user account has been deleted), this key may be omitted. + User object + This is an embedded version of the User object. In certain cases (e.g., when a user account has been deleted), this key may be omitted. annotations list - Metadata about the Channel. See the Annotations documentation. + Metadata about the Channel. See the Annotations documentation. readers ACL object - The access control list that describes who can read this Channel and its Messages. + The access control list that describes who can read this Channel and its Messages. editors @@ -85,12 +85,12 @@ end %> writers ACL object - The access control list that describes who can write Messages to this Channel. + The access control list that describes who can write Messages to this Channel. you_muted boolean - Have you muted this Channel? A user cannot be auto-subscribed to muted channels. + Have you muted this Channel? A user cannot be auto-subscribed to muted channels. you_subscribed @@ -105,22 +105,22 @@ end %> has_unread boolean - Are there unread Messages in this Channel (according to the last_read_id of the Stream Marker you have saved for this Channel)? + Are there unread Messages in this Channel (according to the last_read_id of the Stream Marker you have saved for this Channel)? marker - Stream Marker object - The full Stream Marker object for this Channel. Only sent if using a user access token and requested by the include_marker=1 query string parameter. + Stream Marker object + The full Stream Marker object for this Channel. Only sent if using a user access token and requested by the include_marker=1 query string parameter. recent_message_id string - The ID of the most recent Message in this channel. This may be a deleted Message or a Message from a muted User. + The ID of the most recent Message in this channel. This may be a deleted Message or a Message from a muted User. recent_message Message object - The most recent Message in this channel. This is always included in Channel updates pushed via the streaming API, but must otherwise be requested with the include_recent_message=1 query string parameter. This may be a deleted Message or a Message from a muted User. + The most recent Message in this channel. This is always included in Channel updates pushed via the streaming API, but must otherwise be requested with the include_recent_message=1 query string parameter. This may be a deleted Message or a Message from a muted User. @@ -155,7 +155,7 @@ end %> } ~~~ -Access control lists (ACLs) specify who can edit a channel and read or write Messages to a Channel. In our permissions model, editing implies writings and writing implies reading. Note that `any_user`, `public`, and non-empty `user_ids` are all mutually exclusive (only one of those can be true at a time). Also, the creator of a Channel always has edit access and will not be specified in the `user_ids` list. For some Channel types (like `net.app.core.pm`), the ACLs will be sanitized to make sure they fit a specific schema. Please see the [Messaging overview](/docs/basics/messaging/) for more information. `editors` can edit the channel ACLs, annotations, write messages and perform any action against a channel except for marking it as inactive. Only an owner can mark a channel as inactive. +Access control lists (ACLs) specify who can edit a channel and read or write Messages to a Channel. In our permissions model, editing implies writings and writing implies reading. Note that `any_user`, `public`, and non-empty `user_ids` are all mutually exclusive (only one of those can be true at a time). Also, the creator of a Channel always has edit access and will not be specified in the `user_ids` list. For some Channel types (like `net.app.core.pm`), the ACLs will be sanitized to make sure they fit a specific schema. Please see the [Messaging overview](/docs/guides/messaging/) for more information. `editors` can edit the channel ACLs, annotations, write messages and perform any action against a channel except for marking it as inactive. Only an owner can mark a channel as inactive. ### ACL Fields @@ -171,27 +171,27 @@ Access control lists (ACLs) specify who can edit a channel and read or write any_user boolean - Can any logged in User read/write to this Channel? This will always be false for the editors ACL. If true, public will be false and user_ids will be empty. + Can any logged in User read/write to this Channel? This will always be false for the editors ACL. If true, public will be false and user_ids will be empty. immutable boolean - Can this ACL be changed? In general, we recommend creating immutable Channels so that Messages can't "leak out" of a Channel later. + Can this ACL be changed? In general, we recommend creating immutable Channels so that Messages can't "leak out" of a Channel later. public boolean - Can anyone (including not logged in Users), read this channel. This will always be false for the writers and editors ACLs. If true, any_user will be false and user_ids will be empty. + Can anyone (including not logged in Users), read this channel. This will always be false for the writers and editors ACLs. If true, any_user will be false and user_ids will be empty. user_ids list - A list of strings specifying the ids of Users who can read/write to this Channel. If non-empty, any_user and public will be false. This list can contain at most 200 User ids except for Broadcast channels which allow an unlimited number of readers. + A list of strings specifying the ids of Users who can read/write to this Channel. If non-empty, any_user and public will be false. This list can contain at most 200 User ids except for Broadcast channels which allow an unlimited number of readers. you boolean - Can the authorized User for the current token read/write to this Channel? This field, unlike the others, respects the permission hierarchy. To test channel writeability, you need only examine this field. + Can the authorized User for the current token read/write to this Channel? This field, unlike the others, respects the permission hierarchy. To test channel writeability, you need only examine this field. @@ -200,7 +200,7 @@ Access control lists (ACLs) specify who can edit a channel and read or write include_marker Optional integer (0 or 1) - Should the Stream Marker be included with each Channel? Only available when requested with a user access token. Defaults to false. + Should the Stream Marker be included with each Channel? Only available when requested with a user access token. Defaults to false. include_read Optional integer (0 or 1) - Should Channels with no unread Messages be returned? Defaults to true. + Should Channels with no unread Messages be returned? Defaults to true. include_recent_message Optional integer (0 or 1) - Should the most recent Message be included with each Channel? Defaults to false. + Should the most recent Message be included with each Channel? Defaults to false. include_annotations Optional integer (0 or 1) - Should annotations be included in the response objects? Defaults to false. + Should annotations be included in the response objects? Defaults to false. include_user_annotations Optional integer (0 or 1) - Should User annotations be included in the response objects? Defaults to false. + Should User annotations be included in the response objects? Defaults to false. include_message_annotations Optional integer (0 or 1) - Should Message annotations be included in the response objects? Defaults to false. + Should Message annotations be included in the response objects? Defaults to false. include_inactive Optional integer (0 or 1) - Should inactive channels be included? Defaults to false. + Should inactive channels be included? Defaults to false. -Where noted, endpoints that return a stream of Channels additionally respond to [pagination parameters](/docs/basics/pagination). +Where noted, endpoints that return a stream of Channels additionally respond to [pagination parameters](/reference/make-request/pagination). <%= render 'partials/endpoints-tab', :for => "channel" %> diff --git a/content/docs/resources/channel/lifecycle.md b/content/reference/resources/channel/lifecycle.md similarity index 63% rename from content/docs/resources/channel/lifecycle.md rename to content/reference/resources/channel/lifecycle.md index 20c55e2..0c387aa 100644 --- a/content/docs/resources/channel/lifecycle.md +++ b/content/reference/resources/channel/lifecycle.md @@ -9,13 +9,13 @@ title: "Channel Lifecycle" ## Create a Channel -Create a new [Channel](/docs/resources/channel/). +Create a new [Channel](/reference/resources/channel/). -Send a JSON document that matches the [Channel schema](/docs/resources/channel/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```readers```, ```writers```, ```annotations```, and ```type```. The owner will be auto-subscribed to this channel. +Send a JSON document that matches the [Channel schema](/reference/resources/channel/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```readers```, ```writers```, ```annotations```, and ```type```. The owner will be auto-subscribed to this channel. ### Creating a PM Channel -[PM Channels](/docs/resources/channel/#private-message) (channels of type `net.app.core.pm`) cannot be directly created. Instead they are created for you as necessary when sending a [Message](/docs/resources/message/) using `pm` as a `channel_id`. For more information, see the [Create a Message](/docs/resources/message/lifecycle/#create-a-message) endpoint. +[PM Channels](/reference/resources/channel/#private-message) (channels of type `net.app.core.pm`) cannot be directly created. Instead they are created for you as necessary when sending a [Message](/reference/resources/message/) using `pm` as a `channel_id`. For more information, see the [Create a Message](/reference/resources/message/lifecycle/#create-a-message) endpoint. <%= general_params_note_for "channel" %> @@ -39,7 +39,7 @@ end %> ## Update a Channel -Updates a specific [Channel](/docs/resources/channel/) object. You can update a channel by PUTing an object that matches the [Channel schema](/docs/resources/channel/) with an HTTP header of ```Content-Type: application/json```. The only keys that can be updated are ```annotations```, ```readers```, and ```writers``` (and the ACLs can only be updated if ```immutable=false```). The ```you_can_edit``` property tells you if you are allowed to update a channel. Currently, only the Channel owner can edit a channel. +Updates a specific [Channel](/reference/resources/channel/) object. You can update a channel by PUTing an object that matches the [Channel schema](/reference/resources/channel/) with an HTTP header of ```Content-Type: application/json```. The only keys that can be updated are ```annotations```, ```readers```, and ```writers``` (and the ACLs can only be updated if ```immutable=false```). The ```you_can_edit``` property tells you if you are allowed to update a channel. Currently, only the Channel owner can edit a channel. If you want to add or update a Channel's annotations, you may include the optional ```annotations``` key and pass in the annotations that are changing. @@ -71,7 +71,7 @@ The current user must be the same user who created the Channel. *Editors cannot *net.app.core.pm* channels cannot be marked as inactive. -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= general_params_note_for "channel" %> diff --git a/content/docs/resources/channel/lookup.md b/content/reference/resources/channel/lookup.md similarity index 97% rename from content/docs/resources/channel/lookup.md rename to content/reference/resources/channel/lookup.md index e458ed0..76ae5b9 100644 --- a/content/docs/resources/channel/lookup.md +++ b/content/reference/resources/channel/lookup.md @@ -9,7 +9,7 @@ title: "Channel Lookup" ## Retrieve a Channel -Returns a specific [Channel](/docs/resources/channel/). +Returns a specific [Channel](/reference/resources/channel/). <%= general_params_note_for "channel" %> diff --git a/content/docs/resources/channel/muting.md b/content/reference/resources/channel/muting.md similarity index 80% rename from content/docs/resources/channel/muting.md rename to content/reference/resources/channel/muting.md index e13389d..bfd7822 100644 --- a/content/docs/resources/channel/muting.md +++ b/content/reference/resources/channel/muting.md @@ -9,9 +9,9 @@ title: "Channel Muting" ## Get current user's muted Channels -Retrieve a list of the channels the current user has muted. A user cannot be [auto-subscribed](/docs/basics/messaging/#subscriptions) to muted channels. +Retrieve a list of the channels the current user has muted. A user cannot be [auto-subscribed](/docs/guides/messaging/#subscriptions) to muted channels. -This endpoint is **not** paginated and does **not** respond to the [general channel parameters](/docs/resources/channel/#general-parameters). +This endpoint is **not** paginated and does **not** respond to the [general channel parameters](/reference/resources/channel/#general-parameters). <%= endpoint "GET", "users/me/channels/muted", "User", "public_messages or messages"%> @@ -25,7 +25,7 @@ end %> ## Mute a Channel -Mute a Channel. If a user doesn't want to see a channel until there is a new message, they should [unsubscribe from the channel](/docs/resources/channel/subscriptions/#unsubscribe-from-a-channel) instead of muting it. If a user mutes a channel, they will automatically be unsubscribed from it and cannot be [auto-subscribed](/docs/basics/messaging/#subscriptions) to it. +Mute a Channel. If a user doesn't want to see a channel until there is a new message, they should [unsubscribe from the channel](/reference/resources/channel/subscriptions/#unsubscribe-from-a-channel) instead of muting it. If a user mutes a channel, they will automatically be unsubscribed from it and cannot be [auto-subscribed](/docs/guides/messaging/#subscriptions) to it. <%= general_params_note_for "channel" %> diff --git a/content/docs/resources/channel/search.md b/content/reference/resources/channel/search.md similarity index 78% rename from content/docs/resources/channel/search.md rename to content/reference/resources/channel/search.md index 1c7bf1f..9083f00 100644 --- a/content/docs/resources/channel/search.md +++ b/content/reference/resources/channel/search.md @@ -9,7 +9,7 @@ title: "Channel Search" ## Search for Channels -Returns [Channel](/docs/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. net.patter-app.settings. 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 messages scope. +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. net.patter-app.settings. 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 messages 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. diff --git a/content/docs/resources/channel/subscriptions.md b/content/reference/resources/channel/subscriptions.md similarity index 97% rename from content/docs/resources/channel/subscriptions.md rename to content/reference/resources/channel/subscriptions.md index 006c5aa..68db7df 100644 --- a/content/docs/resources/channel/subscriptions.md +++ b/content/reference/resources/channel/subscriptions.md @@ -35,7 +35,7 @@ end %> ## Subscribe to a Channel -Subscribe to a Channel. This adds it to your [Channel stream](#get-current-users-subscribed-channels). If a user has [muted this Channel](/docs/resources/channel/muting/#mute-a-channel), this call will automatically unmute the Channel. +Subscribe to a Channel. This adds it to your [Channel stream](#get-current-users-subscribed-channels). If a user has [muted this Channel](/reference/resources/channel/muting/#mute-a-channel), this call will automatically unmute the Channel. <%= general_params_note_for "channel" %> diff --git a/content/docs/resources/config/index.md b/content/reference/resources/config/index.md similarity index 81% rename from content/docs/resources/config/index.md rename to content/reference/resources/config/index.md index 67e7d9d..8cf4a35 100644 --- a/content/docs/resources/config/index.md +++ b/content/reference/resources/config/index.md @@ -36,7 +36,7 @@ The Configuration object contains variables which define the current behavior of uri_template_length object - A mapping from each of the possible URI template replacement values to the number of characters that are "used" upon replacement. + A mapping from each of the possible URI template replacement values to the number of characters that are "used" upon replacement. @@ -44,27 +44,27 @@ The Configuration object contains variables which define the current behavior of user Resource Configuration Object - The configuration related to User objects. + The configuration related to User objects. file Resource Configuration Object - The configuration related to File objects. + The configuration related to File objects. post Resource Configuration Object - The configuration related to Post objects. + The configuration related to Post objects. message Resource Configuration Object - The configuration related to Message objects. + The configuration related to Message objects. channel Resource Configuration Object - The configuration related to Channel objects. + The configuration related to Channel objects. @@ -92,12 +92,12 @@ A Resource Configuration object represents values that only apply to a specific annotation_max_bytes integer - The maximum number of bytes that can be attached to this type of object as an Annotation. + The maximum number of bytes that can be attached to this type of object as an Annotation. text_max_length integer - The maximum number of characters that an instance of this object can be. For User objects, this applies to the User description. This field does not apply to Channel objects. + The maximum number of characters that an instance of this object can be. For User objects, this applies to the User description. This field does not apply to Channel objects. diff --git a/content/docs/resources/explore/index.md b/content/reference/resources/explore/index.md similarity index 100% rename from content/docs/resources/explore/index.md rename to content/reference/resources/explore/index.md diff --git a/content/docs/resources/file/content.md b/content/reference/resources/file/content.md similarity index 94% rename from content/docs/resources/file/content.md rename to content/reference/resources/file/content.md index 87377e5..009094a 100644 --- a/content/docs/resources/file/content.md +++ b/content/reference/resources/file/content.md @@ -25,7 +25,7 @@ This endpoint will return a 302 Redirect to a temporary URL for the content of t Set the content for an incomplete File. The content type for this request must be the content type of the file you are uploading. This endpoint can optionally accept a header field `x-adn-filename` to set the File's name. -This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/docs/resources/file/#limits). +This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/reference/resources/file/#limits). <%= endpoint "PUT", "files/[file_id]/content", "User" %> @@ -65,7 +65,7 @@ This endpoint will return a 302 Redirect to a temporary URL for the content of t Set the content for a derived file of an incomplete File. The content type for this request must be the content type of the file you are uploading. This endpoint can optionally accept a header field `x-adn-filename` to set the Derived File's name. -This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this derived file. For more information, see [file storage limits](/docs/resources/file/#limits). +This endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this derived file. For more information, see [file storage limits](/reference/resources/file/#limits). <%= endpoint "PUT", "files/[file_id]/content/[derived_file_key]", "User" %> diff --git a/content/docs/resources/file/index.md b/content/reference/resources/file/index.md similarity index 91% rename from content/docs/resources/file/index.md rename to content/reference/resources/file/index.md index 5fef1db..e217e6d 100644 --- a/content/docs/resources/file/index.md +++ b/content/reference/resources/file/index.md @@ -27,7 +27,7 @@ A file uploaded by a User and hosted by App.net. annotations list - Metadata about the File. See the Annotations documentation. + Metadata about the File. See the Annotations documentation. complete @@ -161,7 +161,7 @@ A file uploaded by a User and hosted by App.net. url_expires string - A date and time indicating when the provided url will no longer be valid. If the expiration has passed, please refetch the File or underlying object to get a new URL to use. + A date and time indicating when the provided url will no longer be valid. If the expiration has passed, please refetch the File or underlying object to get a new URL to use. url_permanent @@ -176,7 +176,7 @@ A file uploaded by a User and hosted by App.net. user object - The User who created this file. + The User who created this file. @@ -219,14 +219,14 @@ Users may include their own derived files when uploading a file with the followi ##### Custom derived files with a complete file -If you're [creating a complete file](/docs/resources/file/lifecycle/#create-a-file), you can specify custom derived files by including a multipart segment for each custom derived file with the key specified in the name field. For example: +If you're [creating a complete file](/reference/resources/file/lifecycle/#create-a-file), you can specify custom derived files by including a multipart segment for each custom derived file with the key specified in the name field. For example: curl -k -H 'Authorization: BEARER ...' https://alpha-api.app.net/stream/0/files -X POST -F 'type=com.example.test' -F "content=@filename.png;type=image/png" -F "derived_key1=@derived_file1.png;type=image/png" -F "derived_key2=@derived_file2.png;type=image/png;filename=overridden.png" ##### Custom derived files with an incomplete file -If you've [created a file](/docs/resources/file/lifecycle/#create-a-file) without any content, you can upload custom derived files in subsequent requests until you complete the file. Either the PUT or POST endpoint can be used. For example: +If you've [created a file](/reference/resources/file/lifecycle/#create-a-file) without any content, you can upload custom derived files in subsequent requests until you complete the file. Either the PUT or POST endpoint can be used. For example: 1. Create an incomplete file: @@ -268,7 +268,7 @@ In general, file content is made available to other users by referencing it in a ## Limits -Paid tier accounts receive 10GB total storage, with a 100MB maximum individual file size. Free tier accounts receive 500MB total storage, with a 10MB maximum individual file size. Individual accounts may have earned additional file storage through the invitation system (see this [blog post](http://blog.app.net/2013/02/25/introducing-a-free-tier/)). To determine the used and available space for an individual user, inspect the `storage` field of their [user token](/docs/resources/token/#retrieve-current-token). +Paid tier accounts receive 10GB total storage, with a 100MB maximum individual file size. Free tier accounts receive 500MB total storage, with a 10MB maximum individual file size. Individual accounts may have earned additional file storage through the invitation system (see this [blog post](http://blog.app.net/2013/02/25/introducing-a-free-tier/)). To determine the used and available space for an individual user, inspect the `storage` field of their [user token](/reference/resources/token/#retrieve-current-token). ## General Parameters @@ -306,28 +306,28 @@ Where noted, File endpoints respond to the following query string parameters: include_annotations Optional integer (0 or 1) - Should annotations be included in the response objects? Defaults to false. + Should annotations be included in the response objects? Defaults to false. include_file_annotations Optional integer (0 or 1) - Should File annotations be included in the response objects? Defaults to false. + Should File annotations be included in the response objects? Defaults to false. include_user_annotations Optional integer (0 or 1) - Should User annotations be included in the response objects? Defaults to false. + Should User annotations be included in the response objects? Defaults to false. -Where noted, endpoints that return a stream of Files additionally respond to [pagination parameters](/docs/basics/pagination). +Where noted, endpoints that return a stream of Files additionally respond to [pagination parameters](/reference/make-request/pagination). ## Attaching Files to other resources -An App.net file can be attached to any resource that allows annotations. You can attach a file to a resource with any annotation by using the [annotation replacement values](/docs/meta/annotations/#annotation-replacement-values). For instance, to attach a photo that you've uploaded as a file to a new post, you would send the following annotations when making your post: +An App.net file can be attached to any resource that allows annotations. You can attach a file to a resource with any annotation by using the [annotation replacement values](/reference/meta/annotations/#annotation-replacement-values). For instance, to attach a photo that you've uploaded as a file to a new post, you would send the following annotations when making your post: ~~~js [ diff --git a/content/docs/resources/file/lifecycle.md b/content/reference/resources/file/lifecycle.md similarity index 78% rename from content/docs/resources/file/lifecycle.md rename to content/reference/resources/file/lifecycle.md index ba58fc9..4d3efdb 100644 --- a/content/docs/resources/file/lifecycle.md +++ b/content/reference/resources/file/lifecycle.md @@ -9,13 +9,13 @@ title: "File Lifecycle" ## Create a File -Create a new [File](/docs/resources/file/). +Create a new [File](/reference/resources/file/). -An App.net File object can be created without setting the file content. This is called an "incomplete" file object. To create an incomplete file object, POST a JSON document that matches the [File schema](/docs/resources/file/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be `kind`, `type`, `name`, `public` and `annotations`. You can also send those keys as standard form data instead of as JSON. Once you have an incomplete file object, you can [set the file content](/docs/resources/file/content/#set-file-content) in a later request. +An App.net File object can be created without setting the file content. This is called an "incomplete" file object. To create an incomplete file object, POST a JSON document that matches the [File schema](/reference/resources/file/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be `kind`, `type`, `name`, `public` and `annotations`. You can also send those keys as standard form data instead of as JSON. Once you have an incomplete file object, you can [set the file content](/reference/resources/file/content/#set-file-content) in a later request. You can also create a complete File object with one request by including the file content with the File metadata. To create a complete file object, send a POST with an HTTP header of `Content-Type: multipart/form-data`. Our API expects one part of the request body to contain a `Content-Disposition` header with a value for `filename` and `name="content"`. The data from this part will be used as the file's content. If you wish to send your data as Base64 encoded instead of as a byte stream you must include a `Content-Transfer-Encoding: base64` header. If there is a part with `name="metadata"` and `Content-Type: application/json` then we will parse that JSON as the file's metadata. Otherwise, we will construct the metadata from the `form-data` sent in the request body. If you send extra parts with a value for `filename`, the `name` -When creating a complete file, this endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/docs/resources/file/#limits). +When creating a complete file, this endpoint could return a `507 Insufficient Storage` error if the user doesn't have enough space for this file. For more information, see [file storage limits](/reference/resources/file/#limits). <%= general_params_note_for "file" %> @@ -62,7 +62,7 @@ Here is some [sample File upload code written in Python](https://gist.github.com ##### Custom derived files -If you'd like to upload [custom derived files](/docs/resources/file/#derived-files) at the same time as the original file, you can include the derived files as extra parts: +If you'd like to upload [custom derived files](/reference/resources/file/#derived-files) at the same time as the original file, you can include the derived files as extra parts: curl -k -H ‘Authorization: BEARER …’ https://alpha-api.app.net/stream/0/files -X POST -F ‘type=com.example.test’ -F “content=@filename.jpg” -F “derived_key1=@derived_file1.png;type=image/png” -F “derived_key2=@derived_file2.png;type=image/png” @@ -70,7 +70,7 @@ If you'd like to upload [custom derived files](/docs/resources/file/#derived-fil ## Update a File -Updates a specific [File](/docs/resources/file/) object. You can update a file by PUTing an object that matches the [File schema](/docs/resources/file/) with an HTTP header of `Content-Type: application/json`. The only keys that can be updated are `annotations`, `name` and `public`. Only the File owner can update a File. +Updates a specific [File](/reference/resources/file/) object. You can update a file by PUTing an object that matches the [File schema](/reference/resources/file/) with an HTTP header of `Content-Type: application/json`. The only keys that can be updated are `annotations`, `name` and `public`. Only the File owner can update a File. This endpoint currently works identically for the `PUT` and `PATCH` HTTP methods. @@ -98,7 +98,7 @@ This endpoint currently works identically for the `PUT` and `PATCH` HTTP methods Delete a file. The current user must be the same user who created the File. It returns the deleted File on success. *Since a File could be referenced by multiple resources we recommend that you don't automatically delete files when you delete Posts. Deleting a file should be a more explicit action taken by the user.* -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= general_params_note_for "file" %> diff --git a/content/docs/resources/file/lookup.md b/content/reference/resources/file/lookup.md similarity index 95% rename from content/docs/resources/file/lookup.md rename to content/reference/resources/file/lookup.md index d0b0ce9..d2a4c91 100644 --- a/content/docs/resources/file/lookup.md +++ b/content/reference/resources/file/lookup.md @@ -9,7 +9,7 @@ title: "File Lookup" ## Retrieve a File -Returns a specific [File](/docs/resources/file/). +Returns a specific [File](/reference/resources/file/). <%= general_params_note_for "file" %> diff --git a/content/docs/resources/filter/index.md b/content/reference/resources/filter/index.md similarity index 98% rename from content/docs/resources/filter/index.md rename to content/reference/resources/filter/index.md index 81a93f8..63fa55b 100644 --- a/content/docs/resources/filter/index.md +++ b/content/reference/resources/filter/index.md @@ -9,7 +9,7 @@ title: "Filter" * TOC {:toc} -A Filter restricts a stream of messages on the server side so your client only sees what it's interested in. [Streams](/docs/resources/app-stream/) are currently the only way to use filters right now. +A Filter restricts a stream of messages on the server side so your client only sees what it's interested in. [Streams](/reference/resources/app-stream/) are currently the only way to use filters right now. ~~~ js { diff --git a/content/docs/resources/filter/lifecycle.md b/content/reference/resources/filter/lifecycle.md similarity index 76% rename from content/docs/resources/filter/lifecycle.md rename to content/reference/resources/filter/lifecycle.md index e4ff722..76f48a0 100644 --- a/content/docs/resources/filter/lifecycle.md +++ b/content/reference/resources/filter/lifecycle.md @@ -9,15 +9,15 @@ title: "Filter Lifecycle" ## Create a Filter -Create a [Filter](/docs/resources/filter/) for the current user. +Create a [Filter](/reference/resources/filter/) for the current user. -Send a JSON document that matches the [Filter schema](/docs/resources/filter/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```name```, ```match_policy``` and ```clauses```. +Send a JSON document that matches the [Filter schema](/reference/resources/filter/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```name```, ```match_policy``` and ```clauses```. <%= endpoint "POST", "filters", "User" %> #### Data -A JSON object representing the [Filter](/docs/resources/filter/) to create. +A JSON object representing the [Filter](/reference/resources/filter/) to create. #### Example @@ -50,7 +50,7 @@ A JSON object representing the [Filter](/docs/resources/filter/) to create. ## Retrieve a Filter -Returns a specific [Filter](/docs/resources/filter/) object. +Returns a specific [Filter](/reference/resources/filter/) object. <%= endpoint "GET", "filters/[filter_id]", "User" %> @@ -85,7 +85,7 @@ Returns a specific [Filter](/docs/resources/filter/) object. ## Get current user's Filters -Return the [Filter](/docs/resources/filter/) for the current user. +Return the [Filter](/reference/resources/filter/) for the current user. <%= endpoint "GET", "filters", "User" %> @@ -119,7 +119,7 @@ Return the [Filter](/docs/resources/filter/) for the current user. ## Update a Filter -Updates a specific [Filter](/docs/resources/filter/) object. When a filter is updated, all the streams using the filter will start using the new filter criteria. You can update a filter by PUTing an object that matches the [Filter schema](/docs/resources/filter/) with an HTTP header of ```Content-Type: application/json```. The entire filter will be replaced with new value but it's ```id``` will remain the same. Please refer to the documentation on [how to create a Filter](#create-a-filter) for more information. +Updates a specific [Filter](/reference/resources/filter/) object. When a filter is updated, all the streams using the filter will start using the new filter criteria. You can update a filter by PUTing an object that matches the [Filter schema](/reference/resources/filter/) with an HTTP header of ```Content-Type: application/json```. The entire filter will be replaced with new value but it's ```id``` will remain the same. Please refer to the documentation on [how to create a Filter](#create-a-filter) for more information. <%= endpoint "PUT", "filters/[filter_id]", "User" %> @@ -164,9 +164,9 @@ Updates a specific [Filter](/docs/resources/filter/) object. When a filter is up ## Delete a Filter -Delete a [Filter](/docs/resources/filter/). The Filter must belong to the current User. It returns the deleted Filter on success. +Delete a [Filter](/reference/resources/filter/). The Filter must belong to the current User. It returns the deleted Filter on success. -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "filters/[filter_id]", "User" %> @@ -201,9 +201,9 @@ Delete a [Filter](/docs/resources/filter/). The Filter must belong to the curren ## Delete all of the current user's Filters -Delete all [Filters](/docs/resources/filter/) for the current user. It returns the deleted Filters on success. +Delete all [Filters](/reference/resources/filter/) for the current user. It returns the deleted Filters on success. -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "filters", "User" %> diff --git a/content/docs/resources/index.md b/content/reference/resources/index.md similarity index 90% rename from content/docs/resources/index.md rename to content/reference/resources/index.md index 79c5d6a..756e56a 100644 --- a/content/docs/resources/index.md +++ b/content/reference/resources/index.md @@ -15,7 +15,7 @@ Guiding principles are: * 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. -* We follow a convention of including the API version number in the resource path. API calls of version 0 are subject to change throughout the process. Once we promote something to version 1, we hope to keep its implementation stable. +* We follow a convention of including the API version number in the resource path. The current API version is version 0. ## Hostname Please use https://alpha-api.app.net/ to access the APIs. diff --git a/content/docs/resources/interaction/index.md b/content/reference/resources/interaction/index.md similarity index 95% rename from content/docs/resources/interaction/index.md rename to content/reference/resources/interaction/index.md index 76a30e9..cd650db 100644 --- a/content/docs/resources/interaction/index.md +++ b/content/reference/resources/interaction/index.md @@ -88,14 +88,14 @@ Interactions are objects that represent users taking certain actions on App.net. ## List User interactions with me -List all the [Interactions](/docs/resources/interaction/) other users have had with me. +List all the [Interactions](/reference/resources/interaction/) other users have had with me. <%= pagination_note %> > Note: you can only request this list for the current user. -> Note: although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/docs/resources/app-stream/) to monitor the global feed for relevant activity. +> Note: although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/reference/resources/app-stream/) to monitor the global feed for relevant activity. This endpoint accepts the `interaction_actions` as a query string parameter whose value is a comma separated list of actions you're interested in. For instance, if you're only interested in repost and follow interactions you could request `stream/0/users/me/interactions?interaction_actions=repost,follow`. diff --git a/content/docs/resources/message/index.md b/content/reference/resources/message/index.md similarity index 79% rename from content/docs/resources/message/index.md rename to content/reference/resources/message/index.md index c2b6577..932612e 100644 --- a/content/docs/resources/message/index.md +++ b/content/reference/resources/message/index.md @@ -9,7 +9,7 @@ title: "Message" * TOC {:toc} -A Message is very similar to a [Post](/docs/resources/post/) but 1) it doesn't have to be public and 2) it will be delivered to an arbitrary set of users (not just the users who follow the Message creator). For an overview of the App.net messaging API, please see the [Introduction to App.net Messaging](/docs/basics/messaging/). +A Message is very similar to a [Post](/reference/resources/post/) but 1) it doesn't have to be public and 2) it will be delivered to an arbitrary set of users (not just the users who follow the Message creator). For an overview of the App.net messaging API, please see the [Introduction to App.net Messaging](/docs/guides/messaging/). ~~~ js { @@ -53,12 +53,12 @@ A Message is very similar to a [Post](/docs/resources/post/) but 1) it doesn't h channel_id string - The id of the Channel this Message belongs to. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed. + The id of the Channel this Message belongs to. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed. user object - This is an embedded version of the User object. In certain cases (e.g., when a user account has been deleted), this key may be omitted. + This is an embedded version of the User object. In certain cases (e.g., when a user account has been deleted), this key may be omitted. created_at @@ -117,12 +117,12 @@ A Message is very similar to a [Post](/docs/resources/post/) but 1) it doesn't h annotations list - Metadata about the entire Message. See the Annotations documentation. + Metadata about the entire Message. See the Annotations documentation. entities object - Rich text information for this message. See the Entities documentation. + Rich text information for this message. See the Entities documentation. is_deleted @@ -138,7 +138,7 @@ A Message is very similar to a [Post](/docs/resources/post/) but 1) it doesn't h ## Message Annotations -Message annotations are immutable attributes that describe the entire message. Please see the [Annotations](/docs/meta/annotations/) documentation for more information. +Message annotations are immutable attributes that describe the entire message. Please see the [Annotations](/reference/meta/annotations/) documentation for more information. ## Machine only Messages @@ -180,29 +180,29 @@ Where noted, Message endpoints respond to the following query string parameters: include_annotations Optional integer (0 or 1) - Should annotations be included in the response objects? Defaults to false. + Should annotations be included in the response objects? Defaults to false. include_message_annotations Optional integer (0 or 1) - Should Message annotations be included in the response objects? Defaults to false. + Should Message annotations be included in the response objects? Defaults to false. include_user_annotations Optional integer (0 or 1) - Should User annotations be included in the response objects? Defaults to false. + Should User annotations be included in the response objects? Defaults to false. include_html Optional integer (0 or 1) - Should the html field be included alongside the text field in the response objects? Defaults to true. + Should the html field be included alongside the text field in the response objects? Defaults to true. -Where noted, endpoints that return a stream of Messages additionally respond to [pagination parameters](/docs/basics/pagination). +Where noted, endpoints that return a stream of Messages additionally respond to [pagination parameters](/reference/make-request/pagination). <%= render 'partials/endpoints-tab', :for => "message" %> diff --git a/content/docs/resources/message/lifecycle.md b/content/reference/resources/message/lifecycle.md similarity index 85% rename from content/docs/resources/message/lifecycle.md rename to content/reference/resources/message/lifecycle.md index c005675..c21a82a 100644 --- a/content/docs/resources/message/lifecycle.md +++ b/content/reference/resources/message/lifecycle.md @@ -9,13 +9,13 @@ title: "Message Lifecycle" ## Create a Message -Create a [Message](/docs/resources/message/) in the specified Channel. +Create a [Message](/reference/resources/message/) in the specified Channel. -Send a JSON document that matches the [Message schema](/docs/resources/message/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```text```, ```reply_to```, ```annotations```, ```entities```, and ```machine_only```. +Send a JSON document that matches the [Message schema](/reference/resources/message/) with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```text```, ```reply_to```, ```annotations```, ```entities```, and ```machine_only```. -If you would like to specify your own entities, please refer to the [user specified entites](/docs/meta/entities/#user-specified-entities) documentation, otherwise we will parse out links, hashtags, and mentions from the ```text``` field. +If you would like to specify your own entities, please refer to the [user specified entites](/reference/meta/entities/#user-specified-entities) documentation, otherwise we will parse out links, hashtags, and mentions from the ```text``` field. -If you want to test how your text will be processed you can use the [text processor](/docs/resources/text-processor). +If you want to test how your text will be processed you can use the [text processor](/reference/resources/text-processor). #### Creating Private Messages for use with net.app.core.pm Channels @@ -26,7 +26,7 @@ To create private group messages for use in `net.app.core.pm` channels, you can <%= endpoint "POST", "channels/[channel_id]/messages", "Varies" %> <%= url_params [ - ["channel_id", 'The id of the Channel in which to create the Message. Alternatively, you can specify pm to auto-create/reuse a net.app.core.pm private message channel.'] + ["channel_id", 'The id of the Channel in which to create the Message. Alternatively, you can specify pm to auto-create/reuse a net.app.core.pm private message channel.'] ]%> #### Generic Channel Example @@ -112,7 +112,7 @@ Delete a message. The current user must be the same user who created the Message *Note: you can always delete a message you created even if you are no longer able to view the rest of the Channel anymore.* -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= general_params_note_for "message" %> diff --git a/content/docs/resources/message/lookup.md b/content/reference/resources/message/lookup.md similarity index 98% rename from content/docs/resources/message/lookup.md rename to content/reference/resources/message/lookup.md index 1b63805..fcbc1c2 100644 --- a/content/docs/resources/message/lookup.md +++ b/content/reference/resources/message/lookup.md @@ -9,7 +9,7 @@ title: "Message Lookup" ## Retrieve a Message -Returns a specific [Message](/docs/resources/message/). +Returns a specific [Message](/reference/resources/message/). *Note: you can always retrieve a message you created even if you are no longer able to view the rest of the Channel anymore.* diff --git a/content/docs/resources/place/index.md b/content/reference/resources/place/index.md similarity index 97% rename from content/docs/resources/place/index.md rename to content/reference/resources/place/index.md index a2a4164..7e9a41a 100644 --- a/content/docs/resources/place/index.md +++ b/content/reference/resources/place/index.md @@ -160,9 +160,9 @@ In the future, Places may eventually sit at multiple categorical "leaf nodes" an ## Attaching Places to other resources -Places can be attached to any resource that allows annotations. You can insert Place data into any annotation using the [`+net.app.core.place` replacement value](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.place.md) and providing a `factual_id`. For more information, see the [annotation replacement values](/docs/meta/annotations/#annotation-replacement-values) documentation. +Places can be attached to any resource that allows annotations. You can insert Place data into any annotation using the [`+net.app.core.place` replacement value](https://github.com/appdotnet/object-metadata/blob/master/annotation-replacement-values/+net.app.core.place.md) and providing a `factual_id`. For more information, see the [annotation replacement values](/reference/meta/annotations/#annotation-replacement-values) documentation. -We provide a [Checkin annotation](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.checkin.md) as a [core annotation](/docs/meta/annotations/#core-annotations) for the common use case of using Place data to give users a way to say "I was here when I posted this", though developers are free to use Place data in other contexts. +We provide a [Checkin annotation](https://github.com/appdotnet/object-metadata/blob/master/annotations/net.app.core.checkin.md) as a [core annotation](/reference/meta/annotations/#core-annotations) for the common use case of using Place data to give users a way to say "I was here when I posted this", though developers are free to use Place data in other contexts. ## Retrieve a Place diff --git a/content/docs/resources/post/index.md b/content/reference/resources/post/index.md similarity index 85% rename from content/docs/resources/post/index.md rename to content/reference/resources/post/index.md index dd62096..4ac14f1 100644 --- a/content/docs/resources/post/index.md +++ b/content/reference/resources/post/index.md @@ -9,7 +9,7 @@ title: "Post" * TOC {:toc} -A Post is the other central object utilized by the App.net Stream API. It has rich text and annotations which comprise all of the content a users sees in their feed. Posts are closely tied to the follow graph. If you want to create data that isn't tied to the follow graph, you should look at [Messages](/docs/resources/message/). +A Post is the other central object utilized by the App.net Stream API. It has rich text and annotations which comprise all of the content a users sees in their feed. Posts are closely tied to the follow graph. If you want to create data that isn't tied to the follow graph, you should look at [Messages](/reference/resources/message/). ~~~ js { @@ -86,7 +86,7 @@ A Post is the other central object utilized by the App.net Stream API. It has ri user object - This is an embedded version of the User object. Note: In certain cases (e.g., when a user + This is an embedded version of the User object. Note: In certain cases (e.g., when a user account has been deleted), this key may be omitted. @@ -166,12 +166,12 @@ A Post is the other central object utilized by the App.net Stream API. It has ri annotations list - Metadata about the entire post. See the Annotations documentation. + Metadata about the entire post. See the Annotations documentation. entities object - Rich text information for this post. See the Entities documentation. + Rich text information for this post. See the Entities documentation. is_deleted @@ -215,7 +215,7 @@ A Post is the other central object utilized by the App.net Stream API. It has ri * ```deleted``` has been deprecated and replaced with ```is_deleted```. This key should not be used and will be removed from the Post object soon. ## Post Annotations -Post annotations are immutable attributes that describe the entire post. Please see the [Annotations](/docs/meta/annotations/) documentation for more information. +Post annotations are immutable attributes that describe the entire post. Please see the [Annotations](/reference/meta/annotations/) documentation for more information. ## Machine only Posts Some posts with annotations data may not be meant for direct consumption by a User. For example, a chess app may create Posts with annotations representing chess moves but having human readable text doesn't make sense. Machine only Posts solve this problem by allowing clients to create posts with ```annotations``` and without ```text```. These posts must be specifically asked for by using the ```include_machine=1``` query string parameter. They must contain at least one annotation and cannot contain any text. When deciding if a Post should be machine only, ask yourself "Would this Post make sense to a human?" @@ -250,7 +250,7 @@ Where noted, Post endpoints respond to the following query string parameters: include_directed_posts Optional integer (0 or 1) - Should Posts directed at people I don't follow be included? A directed Post is a Post that has leading mentions (mentions at the beginning of the text). A machine only Post with mentions is also considered a directed Post. Defaults to false for "My Stream" and true everywhere else. + Should Posts directed at people I don't follow be included? A directed Post is a Post that has leading mentions (mentions at the beginning of the text). A machine only Post with mentions is also considered a directed Post. Defaults to false for "My Stream" and true everywhere else. include_machine @@ -262,47 +262,47 @@ Where noted, Post endpoints respond to the following query string parameters: include_starred_by Optional integer (0 or 1) - Should a sample of Users who have starred a Post be returned with the Post objects? Please see the Post schema. Defaults to false. + Should a sample of Users who have starred a Post be returned with the Post objects? Please see the Post schema. Defaults to false. include_reposters Optional integer (0 or 1) - Should a sample of Users who have reposted a Post be returned with the Post objects? Please see the Post schema. Defaults to false. + Should a sample of Users who have reposted a Post be returned with the Post objects? Please see the Post schema. Defaults to false. include_annotations Optional integer (0 or 1) - Should annotations be included in the response objects? Defaults to false. + Should annotations be included in the response objects? Defaults to false. include_post_annotations Optional integer (0 or 1) - Should Post annotations be included in the response objects? Defaults to false. + Should Post annotations be included in the response objects? Defaults to false. include_user_annotations Optional integer (0 or 1) - Should User annotations be included in the response objects? Defaults to false. + Should User annotations be included in the response objects? Defaults to false. include_html Optional integer (0 or 1) - Should the html field be included alongside the text field in the response objects? Defaults to true. + Should the html field be included alongside the text field in the response objects? Defaults to true. -Where noted, endpoints that return a stream of Posts additionally respond to [pagination parameters](/docs/basics/pagination). +Where noted, endpoints that return a stream of Posts additionally respond to [pagination parameters](/reference/make-request/pagination). ## Stream Faceting parameters -Stream Faceting allows you to filter and query a user's [personalized stream](/docs/resources/post/streams/#retrieve-a-users-personalized-stream) or [unified stream](/docs/resources/post/streams/#retrieve-a-users-unified-stream) with an interface similar to our [Post Search API](/docs/resources/post/search/#search-for-posts). If you use stream faceting, the API will only return recent posts in a user's stream. +Stream Faceting allows you to filter and query a user's [personalized stream](/reference/resources/post/streams/#retrieve-a-users-personalized-stream) or [unified stream](/reference/resources/post/streams/#retrieve-a-users-unified-stream) with an interface similar to our [Post Search API](/reference/resources/post/search/#search-for-posts). If you use stream faceting, the API will only return recent posts in a user's stream. Currently the following stream facets are supported: diff --git a/content/docs/resources/post/lifecycle.md b/content/reference/resources/post/lifecycle.md similarity index 84% rename from content/docs/resources/post/lifecycle.md rename to content/reference/resources/post/lifecycle.md index e6b712f..bb21cb5 100644 --- a/content/docs/resources/post/lifecycle.md +++ b/content/reference/resources/post/lifecycle.md @@ -9,11 +9,11 @@ title: "Post Lifecycle" ## Create a Post -Create a new Post object. Mentions and hashtags will be parsed out of the post text, as will bare URLs. +Create a new Post object. Mentions and hashtags will be parsed out of the post text, as will bare URLs. -You can also create a Post by sending JSON in the HTTP post body that matches the post schema with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```text```, ```reply_to```, ```machine_only```, ```annotations``` and ```entities```. To create complex posts (including [machine only posts](/docs/resources/post/#machine-only-posts)), you must use the JSON interface. See the [JSON example](#json-example) below. If you would like to specify your own entities, please refer to the [user specified entities](/docs/meta/entities/#user-specified-entities) documentation. +You can also create a Post by sending JSON in the HTTP post body that matches the post schema with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```text```, ```reply_to```, ```machine_only```, ```annotations``` and ```entities```. To create complex posts (including [machine only posts](/reference/resources/post/#machine-only-posts)), you must use the JSON interface. See the [JSON example](#json-example) below. If you would like to specify your own entities, please refer to the [user specified entities](/reference/meta/entities/#user-specified-entities) documentation. -If you want to test how your text will be processed you can use the [text processor](/docs/resources/text-processor). +If you want to test how your text will be processed you can use the [text processor](/reference/resources/text-processor). *Note: You cannot reply to a repost. Please reply to the parent Post.* @@ -141,11 +141,11 @@ If you want to test how your text will be processed you can use the [text proces ## Delete a Post -Delete a Post. The current user must be the same user who created the Post. It returns the deleted Post on success. +Delete a Post. The current user must be the same user who created the Post. It returns the deleted Post on success. <%= general_params_note_for "post" %> -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "posts/[post_id]", "User", "write_post" %> diff --git a/content/docs/resources/post/lookup.md b/content/reference/resources/post/lookup.md similarity index 97% rename from content/docs/resources/post/lookup.md rename to content/reference/resources/post/lookup.md index d3cfc84..5b21a6c 100644 --- a/content/docs/resources/post/lookup.md +++ b/content/reference/resources/post/lookup.md @@ -9,7 +9,7 @@ title: "Post Lookup" ## Retrieve a Post -Returns a specific [Post](/docs/resources/post/). +Returns a specific [Post](/reference/resources/post/). <%= general_params_note_for "post" %> diff --git a/content/docs/resources/post/replies.md b/content/reference/resources/post/replies.md similarity index 87% rename from content/docs/resources/post/replies.md rename to content/reference/resources/post/replies.md index ae4ed25..160d53b 100644 --- a/content/docs/resources/post/replies.md +++ b/content/reference/resources/post/replies.md @@ -9,7 +9,7 @@ title: "Post Replies" ## Retrieve the replies to a Post -Retrieve all the [Posts](/docs/resources/post/) that are in the same thread as this post. The specified Post does not have to be the root of the conversation. Additionally, the specified Post will be included in the response at the appropriate place. +Retrieve all the [Posts](/reference/resources/post/) that are in the same thread as this post. The specified Post does not have to be the root of the conversation. Additionally, the specified Post will be included in the response at the appropriate place. **This endpoint would be more accurately named ```stream/0/posts/{post_id}/thread``` and may be renamed in a later API version.** diff --git a/content/docs/resources/post/report.md b/content/reference/resources/post/report.md similarity index 100% rename from content/docs/resources/post/report.md rename to content/reference/resources/post/report.md diff --git a/content/docs/resources/post/reposts.md b/content/reference/resources/post/reposts.md similarity index 98% rename from content/docs/resources/post/reposts.md rename to content/reference/resources/post/reposts.md index 6763a14..8700605 100644 --- a/content/docs/resources/post/reposts.md +++ b/content/reference/resources/post/reposts.md @@ -98,7 +98,7 @@ For compatibility with clients who don't wish to show reposts specially, we set ## Unrepost a Post -Given the original ```post_id```, delete the current user's repost. *Note: this same functionality can be accomplished by [deleting using the repost's post_id](/docs/resources/post/lifecycle/#delete-a-post)*. +Given the original ```post_id```, delete the current user's repost. *Note: this same functionality can be accomplished by [deleting using the repost's post_id](/reference/resources/post/lifecycle/#delete-a-post)*. <%= general_params_note_for "post" %> diff --git a/content/docs/resources/post/search.md b/content/reference/resources/post/search.md similarity index 93% rename from content/docs/resources/post/search.md rename to content/reference/resources/post/search.md index 8c199d8..b04b02c 100644 --- a/content/docs/resources/post/search.md +++ b/content/reference/resources/post/search.md @@ -9,7 +9,7 @@ title: "Post Search" ## Search for Posts -Returns [Post](/docs/resources/post/) objects which match a given search query. Searches ordered by `id` require at least one query or filter to be specified; searches ordered by `score` require at least one query and zero or more filters to be specified. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string. +Returns [Post](/reference/resources/post/) objects which match a given search query. Searches ordered by `id` require at least one query or filter to be specified; searches ordered by `score` require at least one query and zero or more filters to be specified. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string. <%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. Separate lists of terms by spaces. diff --git a/content/docs/resources/post/stars.md b/content/reference/resources/post/stars.md similarity index 94% rename from content/docs/resources/post/stars.md rename to content/reference/resources/post/stars.md index ccac3ea..00ac0d3 100644 --- a/content/docs/resources/post/stars.md +++ b/content/reference/resources/post/stars.md @@ -141,7 +141,7 @@ Remove a Star from a Post. ## Retrieve Posts starred by a User -Get the most recent [Posts](/docs/resources/post/) starred by a specific [User](/docs/resources/user/) in reverse post order. Stars are a way for Users to save posts without rebroadcasting the Post to their followers. +Get the most recent [Posts](/reference/resources/post/) starred by a specific [User](/reference/resources/user/) in reverse post order. Stars are a way for Users to save posts without rebroadcasting the Post to their followers. <%= general_params_note_for "post" %> @@ -153,7 +153,7 @@ Get the most recent [Posts](/docs/resources/post/) starred by a specific [User]( ["user_id", "The user id. If the user id is me the current authenticated user will be used. You can also specify @username as a user_id."] ]%> -*See [General Parameters](/docs/resources/post/#general-parameters) for optional parameters you can use with this query.* +*See [General Parameters](/reference/resources/post/#general-parameters) for optional parameters you can use with this query.* #### Example diff --git a/content/docs/resources/post/streams.md b/content/reference/resources/post/streams.md similarity index 93% rename from content/docs/resources/post/streams.md rename to content/reference/resources/post/streams.md index a3dc7f5..d1ea023 100644 --- a/content/docs/resources/post/streams.md +++ b/content/reference/resources/post/streams.md @@ -9,7 +9,7 @@ title: "Post Streams" ## Retrieve the Global stream -Return the 20 most recent [Posts](/docs/resources/post/) from the Global stream. +Return the 20 most recent [Posts](/reference/resources/post/) from the Global stream. <%= general_params_note_for "post" %> @@ -78,7 +78,7 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the Global stream. ## Retrieve Posts created by a User -Get the most recent [Posts](/docs/resources/post/) created by a specific [User](/docs/resources/user/) in reverse post order. +Get the most recent [Posts](/reference/resources/post/) created by a specific [User](/reference/resources/user/) in reverse post order. <%= general_params_note_for "post" %> @@ -151,7 +151,7 @@ Get the most recent [Posts](/docs/resources/post/) created by a specific [User]( ## Retrieve Posts mentioning a User -Get the most recent [Posts](/docs/resources/post/) mentioning by a specific [User](/docs/resources/user/) in reverse post order. +Get the most recent [Posts](/reference/resources/post/) mentioning by a specific [User](/reference/resources/user/) in reverse post order. <%= general_params_note_for "post" %> @@ -224,7 +224,7 @@ Get the most recent [Posts](/docs/resources/post/) mentioning by a specific [Use ## Retrieve a User's personalized stream -Return the 20 most recent [Posts](/docs/resources/post/) from the current User and the Users they follow. +Return the 20 most recent [Posts](/reference/resources/post/) from the current User and the Users they follow. <%= general_params_note_for "post" %> @@ -295,7 +295,7 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current User a ## Retrieve a User's unified stream -Return the 20 most recent [Posts](/docs/resources/post/) from the current user's [personalized stream](#retrieve-a-users-personalized-stream) and [mentions stream](#retrieve-posts-mentioning-a-user) merged into one stream. +Return the 20 most recent [Posts](/reference/resources/post/) from the current user's [personalized stream](#retrieve-a-users-personalized-stream) and [mentions stream](#retrieve-posts-mentioning-a-user) merged into one stream. <%= general_params_note_for "post" %> @@ -366,7 +366,7 @@ Return the 20 most recent [Posts](/docs/resources/post/) from the current user's ## Retrieve tagged Posts -Return the 20 most recent [Posts](/docs/resources/post/) for a specific hashtag. +Return the 20 most recent [Posts](/reference/resources/post/) for a specific hashtag. <%= general_params_note_for "post" %> diff --git a/content/docs/resources/stream-marker/index.md b/content/reference/resources/stream-marker/index.md similarity index 83% rename from content/docs/resources/stream-marker/index.md rename to content/reference/resources/stream-marker/index.md index 5e39d00..2fd2f18 100644 --- a/content/docs/resources/stream-marker/index.md +++ b/content/reference/resources/stream-marker/index.md @@ -7,7 +7,7 @@ title: "Stream Marker" * TOC {:toc} -Stream markers allows a User's position in a stream of Posts to be synced between multiple App.net clients. Then when you go from the browser to your phone, your stream is right where you left off. The current stream marker will be included in the [response envelope](/docs/basics/responses/#response-envelope) from any stream that returns Posts. +Stream markers allows a User's position in a stream of Posts to be synced between multiple App.net clients. Then when you go from the browser to your phone, your stream is right where you left off. The current stream marker will be included in the [response envelope](/reference/make-request/responses/#response-envelope) from any stream that returns Posts. ## Example Stream Marker @@ -74,9 +74,9 @@ A marker that has been set will look like this: ## Update a Stream Marker -Update the User's current place in a Stream. To update a Stream Marker, you can POST an object that matches the [Stream Marker schema](/docs/resources/stream-marker/) with an HTTP header of ```Content-Type: application/json```. Only the ```id```, ```name```, and ```percentage``` fields will be used. ```name``` will come from the marker you received in the last GET request you made for the stream. You can update multiple stream markers at once by POSTing a list of stream markers instead of a single one. +Update the User's current place in a Stream. To update a Stream Marker, you can POST an object that matches the [Stream Marker schema](/reference/resources/stream-marker/) with an HTTP header of ```Content-Type: application/json```. Only the ```id```, ```name```, and ```percentage``` fields will be used. ```name``` will come from the marker you received in the last GET request you made for the stream. You can update multiple stream markers at once by POSTing a list of stream markers instead of a single one. -The purpose of a Stream Marker is _not_ to allow a user to scroll a stream on one device and see the scroll happen on another device in realtime. A stream marker should only be updated when a user has stopped scrolling (i.e. the stream's position hasn't changed in multiple seconds) or when the app is being closed. Please make sure your code understands our [rate limit headers](/docs/basics/rate-limits/#response-headers) so if the rate limits for this endpoint change in the future your app handles this gracefully. +The purpose of a Stream Marker is _not_ to allow a user to scroll a stream on one device and see the scroll happen on another device in realtime. A stream marker should only be updated when a user has stopped scrolling (i.e. the stream's position hasn't changed in multiple seconds) or when the app is being closed. Please make sure your code understands our [rate limit headers](/reference/make-request/rate-limits/#response-headers) so if the rate limits for this endpoint change in the future your app handles this gracefully. The `last_read_id` is updated if the provided `id` is larger than the current value of `last_read_id`. If you would like to explicitly set the `last_read_id` to a smaller value, you can pass the query string parameter `reset_read_id=1` when updating a stream marker. diff --git a/content/docs/resources/text-processor/index.md b/content/reference/resources/text-processor/index.md similarity index 66% rename from content/docs/resources/text-processor/index.md rename to content/reference/resources/text-processor/index.md index b533d9d..3c81ade 100644 --- a/content/docs/resources/text-processor/index.md +++ b/content/reference/resources/text-processor/index.md @@ -9,7 +9,7 @@ title: "Text Processor" ## Process text -When a request is made to [create a Post](/docs/resources/post/lifecycle/#create-a-post) or [Message](/docs/resources/message/lifecycle/#create-a-message), or [update a User profile](/docs/resources/user/profile/#update-a-user) description, the provided body text is processed for [entities](/docs/meta/entities). You can use this endpoint to test how App.net will parse text for entities as well as render text as html. You can test specifying your own entities by sending a [complete JSON object](/docs/resources/post/lifecycle/#json-example) as documented under [Post creation](/docs/resources/post/lifecycle/#create-a-post). Calls to this endpoint will not create or update any objects in App.net. +When a request is made to [create a Post](/reference/resources/post/lifecycle/#create-a-post) or [Message](/reference/resources/message/lifecycle/#create-a-message), or [update a User profile](/reference/resources/user/profile/#update-a-user) description, the provided body text is processed for [entities](/reference/meta/entities). You can use this endpoint to test how App.net will parse text for entities as well as render text as html. You can test specifying your own entities by sending a [complete JSON object](/reference/resources/post/lifecycle/#json-example) as documented under [Post creation](/reference/resources/post/lifecycle/#create-a-post). Calls to this endpoint will not create or update any objects in App.net. <%= endpoint "POST", "text/process", "Any" %> diff --git a/content/docs/resources/token/index.md b/content/reference/resources/token/index.md similarity index 89% rename from content/docs/resources/token/index.md rename to content/reference/resources/token/index.md index 9dfcff5..04a11f3 100644 --- a/content/docs/resources/token/index.md +++ b/content/reference/resources/token/index.md @@ -9,7 +9,7 @@ title: "Token" ## Retrieve current token -Returns info about the current [OAuth access token](/docs/authentication/#access-tokens). If the token is a user token the response will include a [User](/docs/resources/user/) object. +Returns info about the current [OAuth access token](/reference/authentication/#access-tokens). If the token is a user token the response will include a [User](/reference/resources/user/) object. <%= endpoint "GET", "token", "Any" %> @@ -82,7 +82,7 @@ Requested with a user access token: ## Deauthorize current token -Deauthorize the current [OAuth access token](/docs/authentication/#access-tokens). This works for User tokens and App tokens. +Deauthorize the current [OAuth access token](/reference/authentication/#access-tokens). This works for User tokens and App tokens. <%= endpoint "DELETE", "token", "Any" %> @@ -129,7 +129,7 @@ Requested with a user access token: ## Retrieve authorized User IDs for an app -Returns a list of ids of Users that have authorized an app. Must be requested using an [app access token](/docs/authentication/#access-tokens). +Returns a list of ids of Users that have authorized an app. Must be requested using an [app access token](/reference/authentication/#access-tokens). <%= endpoint "GET", "apps/me/tokens/user_ids", "App" %> @@ -152,7 +152,7 @@ Returns a list of ids of Users that have authorized an app. Must be requested us ## Retrieve authorized User tokens for an app -Returns a list of User tokens corresponding to an app token. Must be requested using an [app access token](/docs/authentication/#access-tokens). +Returns a list of User tokens corresponding to an app token. Must be requested using an [app access token](/reference/authentication/#access-tokens). <%= pagination_note %> diff --git a/content/docs/resources/user-stream/index.md b/content/reference/resources/user-stream/index.md similarity index 94% rename from content/docs/resources/user-stream/index.md rename to content/reference/resources/user-stream/index.md index 2589ffe..6675898 100644 --- a/content/docs/resources/user-stream/index.md +++ b/content/reference/resources/user-stream/index.md @@ -11,7 +11,7 @@ title: "User Stream" ## Overview -A User Stream is a long-lived connection that allows an app to receive real-time updates on a user's behalf. If you would like to receive information on behalf of multiple users (or process all public App.net data), please use an [App Stream](/docs/resources/app-stream). Unlike App Streams (which must be used on a server), User Streams can be used by any App.net client. +A User Stream is a long-lived connection that allows an app to receive real-time updates on a user's behalf. If you would like to receive information on behalf of multiple users (or process all public App.net data), please use an [App Stream](/reference/resources/app-stream). Unlike App Streams (which must be used on a server), User Streams can be used by any App.net client. User Streams are not meant to be a global firehose from App.net. Rather, user streams are based on the idea of subscriptions. Essentially, your app makes normal API calls to App.net and then subscribes to future updates from that endpoint. Each User Stream is identified by a `connection_id` and has multiple subscriptions (which correspond to normal API endpoints) and are identified by `subscription_id`. @@ -23,7 +23,7 @@ Since memory and bandwidth is not unlimited, each Stream has associated limits. ### Creating a User Stream -A client opens a User Stream by making an authenticated connection to the user stream endpoint. The authentication token may be passed in headers or the query string [like the rest of the API](/docs/authentication/#making-authenticated-api-requests). +A client opens a User Stream by making an authenticated connection to the user stream endpoint. The authentication token may be passed in headers or the query string [like the rest of the API](/reference/authentication/#making-authenticated-api-requests). The User Stream endpoint is `stream-channel.app.net/stream/user` and can be accessed via WebSocket or standard HTTP: @@ -54,7 +54,7 @@ Clients may begin receiving events on the stream **before** the JSON API call re ### Client consumes stream events -Each stream message is a JSON blob that matches the [response format](/docs/basics/responses/#response-envelope) returned by the JSON API. If you are consuming a User Stream with WebSockets, each frame will be a separate JSON blob. If you are using the HTTP interface, the response will be encoded with ```Transfer-Encoding: chunked``` and each stream message is separated by ```\r\n```. +Each stream message is a JSON blob that matches the [response format](/reference/make-request/responses/#response-envelope) returned by the JSON API. If you are consuming a User Stream with WebSockets, each frame will be a separate JSON blob. If you are using the HTTP interface, the response will be encoded with ```Transfer-Encoding: chunked``` and each stream message is separated by ```\r\n```. Once the JSON is parsed, each message will include the `subscription_ids` which is a list of all subscriptions this message matches. If the original endpoint supported pagination, updated pagination keys `max_id`, `min_id` and `more` will be included. `more` will always be false in the case of streaming events. Events may contain multiple data objects. The `subscription_ids` should be used by your stream consumer to decide how to process the streaming event. diff --git a/content/docs/resources/user-stream/lifecycle.md b/content/reference/resources/user-stream/lifecycle.md similarity index 64% rename from content/docs/resources/user-stream/lifecycle.md rename to content/reference/resources/user-stream/lifecycle.md index 53113ab..0b19b50 100644 --- a/content/docs/resources/user-stream/lifecycle.md +++ b/content/reference/resources/user-stream/lifecycle.md @@ -9,11 +9,11 @@ title: "User Stream Lifecycle" ## Delete a User Stream -Delete a [User Stream](/docs/resources/user-stream/). The User Stream must belong to the current token. It disconnects any sockets with this User Stream open and returns an HTTP 204 No Content on success. +Delete a [User Stream](/reference/resources/user-stream/). The User Stream must belong to the current token. It disconnects any sockets with this User Stream open and returns an HTTP 204 No Content on success. -If you'd like your user stream to be automatically deleted when you disconnect from it, please add the [`auto_delete=1`](/docs/resources/user-stream/#limits) query string parameter when you create the user stream. +If you'd like your user stream to be automatically deleted when you disconnect from it, please add the [`auto_delete=1`](/reference/resources/user-stream/#limits) query string parameter when you create the user stream. -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "users/me/streams/[connection_id]", "User" %> @@ -29,9 +29,9 @@ If you'd like your user stream to be automatically deleted when you disconnect f ## Delete a User Stream subscription -Delete a subscription of a [User Stream](/docs/resources/user-stream/). The User Stream must belong to the current token. It returns an HTTP 204 No Content on success. +Delete a subscription of a [User Stream](/reference/resources/user-stream/). The User Stream must belong to the current token. It returns an HTTP 204 No Content on success. -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "users/me/streams/[connection_id]/[subscription_id]", "User" %> diff --git a/content/docs/resources/user/blocking.md b/content/reference/resources/user/blocking.md similarity index 78% rename from content/docs/resources/user/blocking.md rename to content/reference/resources/user/blocking.md index 8a29192..0e923b7 100644 --- a/content/docs/resources/user/blocking.md +++ b/content/reference/resources/user/blocking.md @@ -11,7 +11,7 @@ title: "User Blocking" Block a user from seeing your App.net content. This means the user will not be able to see, star, reply to, or repost your content. This user will also effectively be muted for you. This will automatically unfollow both users from each other. A user may be able to tell if they've been blocked by a user. For instance if @mthurman blocks @berg and @berg logs out of alpha.app.net, he could see @mthurman's profile. -In most cases, [muting a user](/docs/resources/user/muting/#mute-a-user) is probably sufficient since that hides all of a user's content from you. If a user is aggressively reposting or starring your content, blocking them will prevent them from interacting with your content at all. +In most cases, [muting a user](/reference/resources/user/muting/#mute-a-user) is probably sufficient since that hides all of a user's content from you. If a user is aggressively reposting or starring your content, blocking them will prevent them from interacting with your content at all. <%= general_params_note_for "user" %> @@ -36,7 +36,7 @@ Allow a blocked user to interact with my content. <%= general_params_note_for "user" %> -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "users/[user_id]/block", "User", "follow" %> @@ -62,7 +62,7 @@ Retrieve a list of blocked users. <%= endpoint "GET", "users/[user_id]/blocked", "Any" %> <%= url_params [ - ["user_id",'The id of the user to retrieve a list of muted users for. If requested with a user token you can request blocked users for the current user by using me as the user id. If requested with an app token you can request blocked users for any user that has authorized your app.'] + ["user_id",'The id of the user to retrieve a list of muted users for. If requested with a user token you can request blocked users for the current user by using me as the user id. If requested with an app token you can request blocked users for any user that has authorized your app.'] ]%> #### Example diff --git a/content/docs/resources/user/following.md b/content/reference/resources/user/following.md similarity index 85% rename from content/docs/resources/user/following.md rename to content/reference/resources/user/following.md index 1d2efc3..7fd877d 100644 --- a/content/docs/resources/user/following.md +++ b/content/reference/resources/user/following.md @@ -9,7 +9,7 @@ title: "User Following" ## Follow a User -Returns the User object of the user being followed. +Returns the User object of the user being followed. <%= general_params_note_for "user" %> @@ -29,11 +29,11 @@ end %> ## Unfollow a User -Returns the User object of the user being unfollowed. +Returns the User object of the user being unfollowed. <%= general_params_note_for "user" %> -*Remember, access tokens cannot be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens cannot be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "users/[user_id]/follow", "User", "follow" %> @@ -51,7 +51,7 @@ end %> ## List users a user is following -Returns a list of User objects the specified user is following. +Returns a list of User objects the specified user is following. <%= general_params_note_for "user" %> @@ -75,7 +75,7 @@ end %> ## List users following a user -Returns a list of User objects for users following the specified user. Please note that the pagination is not based on user or post ids. +Returns a list of User objects for users following the specified user. Please note that the pagination is not based on user or post ids. <%= general_params_note_for "user" %> diff --git a/content/docs/resources/user/index.md b/content/reference/resources/user/index.md similarity index 91% rename from content/docs/resources/user/index.md rename to content/reference/resources/user/index.md index c1b9071..65a27c1 100644 --- a/content/docs/resources/user/index.md +++ b/content/reference/resources/user/index.md @@ -72,7 +72,7 @@ A User is the central object of the App.net APIs. User objects have usernames, f entities object - Entities included in biographical information. See information on entities for reference. + Entities included in biographical information. See information on entities for reference. @@ -179,7 +179,7 @@ A User is the central object of the App.net APIs. User objects have usernames, f annotations list - Metadata about the user. See the Annotations documentation. + Metadata about the user. See the Annotations documentation. canonical_url @@ -210,7 +210,7 @@ will be returned with HTTPS URLs, but can be fetched over HTTP if desired. **Currently, gif images can not be resized with the ```w``` and ```h``` parameters.** -A user's avatar and cover images can be [directly requested](/docs/resources/user/profile/#retrieve-a-users-avatar-image) without requesting the entire user object. +A user's avatar and cover images can be [directly requested](/reference/resources/user/profile/#retrieve-a-users-avatar-image) without requesting the entire user object. ## Account Types @@ -242,23 +242,23 @@ Where noted, User endpoints respond to the following query string parameters: include_annotations Optional integer (0 or 1) - Should annotations be included in the response objects? Defaults to false. + Should annotations be included in the response objects? Defaults to false. include_user_annotations Optional integer (0 or 1) - Should User annotations be included in the response objects? Defaults to false. + Should User annotations be included in the response objects? Defaults to false. include_html Optional integer (0 or 1) - Should the user description html field be included alongside the text field in the response objects? Defaults to true. + Should the user description html field be included alongside the text field in the response objects? Defaults to true. -Where noted, endpoints that return a stream of Users additionally respond to [pagination parameters](/docs/basics/pagination). +Where noted, endpoints that return a stream of Users additionally respond to [pagination parameters](/reference/make-request/pagination). <%= render 'partials/endpoints-tab', :for => "user" %> diff --git a/content/docs/resources/user/lookup.md b/content/reference/resources/user/lookup.md similarity index 95% rename from content/docs/resources/user/lookup.md rename to content/reference/resources/user/lookup.md index c67ae5f..e2cc907 100644 --- a/content/docs/resources/user/lookup.md +++ b/content/reference/resources/user/lookup.md @@ -9,7 +9,7 @@ title: "User Lookup" ## Retrieve a User -Returns a specific User object. +Returns a specific User object. <%= general_params_note_for "user" %> diff --git a/content/docs/resources/user/muting.md b/content/reference/resources/user/muting.md similarity index 83% rename from content/docs/resources/user/muting.md rename to content/reference/resources/user/muting.md index cf1ac63..8a65886 100644 --- a/content/docs/resources/user/muting.md +++ b/content/reference/resources/user/muting.md @@ -33,7 +33,7 @@ Stop hiding all posts for a given user. <%= general_params_note_for "user" %> -*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/docs/authentication/#making-authenticated-api-requests).* +*Remember, access tokens can not be passed in a HTTP body for ```DELETE``` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* <%= endpoint "DELETE", "users/[user_id]/mute", "User", "follow" %> @@ -58,7 +58,7 @@ Retrieve a list of muted users. <%= endpoint "GET", "users/[user_id]/muted", "Any" %> <%= url_params [ - ["user_id",'The id of the user to retrieve a list of muted users for. If requested with a user token you can request muted users for the current user by using me as the user id. If requested with an app token you can request muted users for any user that has authorized your app.'] + ["user_id",'The id of the user to retrieve a list of muted users for. If requested with a user token you can request muted users for the current user by using me as the user id. If requested with an app token you can request muted users for any user that has authorized your app.'] ]%> #### Example diff --git a/content/docs/resources/user/post-interactions.md b/content/reference/resources/user/post-interactions.md similarity index 100% rename from content/docs/resources/user/post-interactions.md rename to content/reference/resources/user/post-interactions.md diff --git a/content/docs/resources/user/profile.md b/content/reference/resources/user/profile.md similarity index 82% rename from content/docs/resources/user/profile.md rename to content/reference/resources/user/profile.md index 0093724..4bca5a5 100644 --- a/content/docs/resources/user/profile.md +++ b/content/reference/resources/user/profile.md @@ -9,9 +9,9 @@ title: "User Profile" ## Update a User -Updates a specific user's profile details. You can update a user by PUTing an object that matches the [User schema](/docs/resources/user/) with an HTTP header of ```Content-Type: application/json```. You must provide values for each of the following keys: ```name```, ```locale```, ```timezone```, and ```description```. If you would only like to update a subset of those keys, you can also [partially update a user](#partially-update-a-user). +Updates a specific user's profile details. You can update a user by PUTing an object that matches the [User schema](/reference/resources/user/) with an HTTP header of ```Content-Type: application/json```. You must provide values for each of the following keys: ```name```, ```locale```, ```timezone```, and ```description```. If you would only like to update a subset of those keys, you can also [partially update a user](#partially-update-a-user). -For the description, you must specify ```description.text``` as a child key. You can also specify [custom links](/docs/meta/entities/#user-specified-entities) for a user description. If you want to test how your text will be processed you can use the [text processor](/docs/resources/text-processor). +For the description, you must specify ```description.text``` as a child key. You can also specify [custom links](/reference/meta/entities/#user-specified-entities) for a user description. If you want to test how your text will be processed you can use the [text processor](/reference/resources/text-processor). If you want to add or update a User's annotations, you may include the optional ```annotations``` key and pass in the annotations that are changing. @@ -46,7 +46,7 @@ end %> ## Partially Update a User -Updates a subset of a specific user's profile details. You can update a user by passing the keys you'd like to update from the [User schema](/docs/resources/user/) with an HTTP header of ```Content-Type: application/json```. You can also specify [custom links](/docs/meta/entities/#user-specified-entities) for a user description. If you want to test how your text will be processed you can use the [text processor](/docs/resources/text-processor). +Updates a subset of a specific user's profile details. You can update a user by passing the keys you'd like to update from the [User schema](/reference/resources/user/) with an HTTP header of ```Content-Type: application/json```. You can also specify [custom links](/reference/meta/entities/#user-specified-entities) for a user description. If you want to test how your text will be processed you can use the [text processor](/reference/resources/text-processor). <%= general_params_note_for "user" %> @@ -66,7 +66,7 @@ end %> ## Retrieve a User's avatar image -Retrieve a User's avatar image. This endpoint does not require authentication, is not rate limited, and will return an HTTP 302 redirect to the user's current avatar image. It will include any [query string parameters](/docs/resources/user/#images) you pass to the endpoint. +Retrieve a User's avatar image. This endpoint does not require authentication, is not rate limited, and will return an HTTP 302 redirect to the user's current avatar image. It will include any [query string parameters](/reference/resources/user/#images) you pass to the endpoint. <%= endpoint "GET", "users/[user_id]/avatar", "None" %> @@ -122,7 +122,7 @@ end %> ## Retrieve a User's cover image -Retrieve a User's cover image. This endpoint does not require authentication, is not rate limited, and will return an HTTP 302 redirect to the user's current cover image. It will include any [query string parameters](/docs/resources/user/#images) you pass to the endpoint. +Retrieve a User's cover image. This endpoint does not require authentication, is not rate limited, and will return an HTTP 302 redirect to the user's current cover image. It will include any [query string parameters](/reference/resources/user/#images) you pass to the endpoint. <%= endpoint "GET", "users/[user_id]/cover", "None" %> diff --git a/layouts/default.html b/layouts/default.html index 8d52a71..a359446 100644 --- a/layouts/default.html +++ b/layouts/default.html @@ -16,14 +16,6 @@
          \ No newline at end of file +

        From 4a934fe72a7ad4a0b4929740569ca1f73216e6c4 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 17 Mar 2014 15:48:19 -0700 Subject: [PATCH 167/231] Some small tweaks --- content/docs/guides/create-an-app.md | 2 +- content/reference/authentication/flows/web.md | 4 +++- content/reference/resources/message/index.md | 2 +- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/content/docs/guides/create-an-app.md b/content/docs/guides/create-an-app.md index ec25c95..38b8c45 100644 --- a/content/docs/guides/create-an-app.md +++ b/content/docs/guides/create-an-app.md @@ -29,7 +29,7 @@ You will be able to change all of this later, but start by giving your app a nam Enter a website that is most closely related to this app. If it doesn't make sense for you to enter a website feel free to enter in your Alpha profile URL. (https://app.net/). This will let others know who is responsible for this app. -The **Callback URL** is prefilled with http://localhost:8000 as a convenience for local development. The Callback URL will be used when you [authenticate your app](/reference/authentication/) later. +The **Redirect URL** is prefilled with http://localhost:8000 as a convenience for local development. The Redirect URL will be used when you [authenticate your app](/reference/authentication/) later. When you are satisfied with the information you have entered click create. diff --git a/content/reference/authentication/flows/web.md b/content/reference/authentication/flows/web.md index fb9d591..c367375 100644 --- a/content/reference/authentication/flows/web.md +++ b/content/reference/authentication/flows/web.md @@ -11,7 +11,9 @@ title: "Web Flows" This is the easiest way to get an access token—we recommend it to most users of the API. If you're writing an app on a server using a language like Ruby, Python, PHP, Java, etc. you should use this flow. -**You must keep your client_secret confidential**. That means that you may not include it in the source code or binary of an application that you ship to end-users, even in obscured form. +**You must keep your `client_secret` confidential**. That means that you may not include it in the source code or binary of an application that you ship to end-users, even in obscured form. + +Your `redirect_uri` must be registered with App.net before you can use it. 1. Direct the user that you want to authenticate to this URL: diff --git a/content/reference/resources/message/index.md b/content/reference/resources/message/index.md index 932612e..1c39a1f 100644 --- a/content/reference/resources/message/index.md +++ b/content/reference/resources/message/index.md @@ -142,7 +142,7 @@ Message annotations are immutable attributes that describe the entire message. P ## Machine only Messages -Sometimes a Message is not meant for human consumption but it may be readable by an App of some kind. In that case, you can create a machine only Message by including `annotations` and not including `text`. You can request machine only Messages using the `include_machine=1` query string parameter. +Sometimes a Message is not meant for human consumption but it may be readable by an App of some kind. In that case, you can create a machine only Message by including `annotations`, omitting `text`, and setting `machine_only: true`. You can request machine only Messages using the `include_machine=1` query string parameter. ## General Parameters From cb1e64fc2e1ff1b78ad685606b9734af5bbe2d32 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Mon, 17 Mar 2014 15:51:04 -0700 Subject: [PATCH 168/231] Make user search its own page --- content/reference/resources/user/lookup.md | 19 --------------- content/reference/resources/user/search.md | 27 ++++++++++++++++++++++ layouts/partials/endpoints/user.md | 2 +- layouts/partials/reference_nav.html | 1 + 4 files changed, 29 insertions(+), 20 deletions(-) create mode 100644 content/reference/resources/user/search.md diff --git a/content/reference/resources/user/lookup.md b/content/reference/resources/user/lookup.md index e2cc907..b5f1545 100644 --- a/content/reference/resources/user/lookup.md +++ b/content/reference/resources/user/lookup.md @@ -61,22 +61,3 @@ Returns multiple Users requested by id. At most 200 users can be requested. } } ~~~ - -## Search for Users - -Search the App.net userbase. - -<%= general_params_note_for "user" %> - -<%= endpoint "GET", "users/search", "Any" %> - -<%= query_params [ - ["q","The search query. Supports @username or #tag searches as well as normal search terms. Searches username, display name, bio information. Does not search posts."], - ["count","(Optional) The number of Users to return, up to a maximum of 200. Defaults to 20 if not specified."] -]%> - -#### Example - -> GET https://alpha-api.app.net/stream/0/users/search?q=%23api - -<%= collection_response(:user) %> diff --git a/content/reference/resources/user/search.md b/content/reference/resources/user/search.md new file mode 100644 index 0000000..95206ab --- /dev/null +++ b/content/reference/resources/user/search.md @@ -0,0 +1,27 @@ +--- +title: "User Search" +--- + +# Search + +* TOC +{:toc} + +## Search for Users + +Search the App.net userbase. + +<%= general_params_note_for "user" %> + +<%= endpoint "GET", "users/search", "Any" %> + +<%= query_params [ + ["q","The search query. Supports @username or #tag searches as well as normal search terms. Searches username, display name, bio information. Does not search posts."], + ["count","(Optional) The number of Users to return, up to a maximum of 200. Defaults to 20 if not specified."] +]%> + +#### Example + +> GET https://alpha-api.app.net/stream/0/users/search?q=%23api + +<%= collection_response(:user) %> diff --git a/layouts/partials/endpoints/user.md b/layouts/partials/endpoints/user.md index d7a0018..4675abe 100644 --- a/layouts/partials/endpoints/user.md +++ b/layouts/partials/endpoints/user.md @@ -93,7 +93,7 @@ Any - Search for Users + Search for Users GET /stream/0/users/search Any diff --git a/layouts/partials/reference_nav.html b/layouts/partials/reference_nav.html index 562cfa5..bef4bd5 100644 --- a/layouts/partials/reference_nav.html +++ b/layouts/partials/reference_nav.html @@ -30,6 +30,7 @@
      • Muting
      • Blocking
      • Post Interactions
        • +
      • Search
    • Post
      •  -{::options parse_block_html="true" /} -
      \ No newline at end of file +
      From 8e7035f3582af662f41f0ae037437c00165a3637 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 2 Apr 2014 14:30:30 -0700 Subject: [PATCH 219/231] Rearrange auth page Also, oauth2 is now a standard --- .../authentication/flows/app-access-token.md | 2 +- content/reference/authentication/flows/web.md | 2 +- content/reference/authentication/index.md | 89 +++++++++---------- content/reference/index.md | 2 +- 4 files changed, 44 insertions(+), 51 deletions(-) diff --git a/content/reference/authentication/flows/app-access-token.md b/content/reference/authentication/flows/app-access-token.md index 7f85b2b..811ed8a 100644 --- a/content/reference/authentication/flows/app-access-token.md +++ b/content/reference/authentication/flows/app-access-token.md @@ -19,7 +19,7 @@ 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/draft-ietf-oauth-v2-31#section-2.3.1). +> 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). App.net will respond with a JSON-encoded token: diff --git a/content/reference/authentication/flows/web.md b/content/reference/authentication/flows/web.md index c367375..0f06029 100644 --- a/content/reference/authentication/flows/web.md +++ b/content/reference/authentication/flows/web.md @@ -45,7 +45,7 @@ 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/draft-ietf-oauth-v2-31#section-2.3.1). + > 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). 1. App.net will respond with a JSON-encoded token: `{"access_token": "[user access token]", "token": {...Token object...}}` diff --git a/content/reference/authentication/index.md b/content/reference/authentication/index.md index 16c4f96..1c69abc 100644 --- a/content/reference/authentication/index.md +++ b/content/reference/authentication/index.md @@ -9,58 +9,39 @@ title: "Authentication" As a developer working with App.net, you are required to follow some simple rules to ensure that the privacy and security of user data is protected. To help you achieve that, we've put together this document on how to authenticate with App.net. -All requests to the API—authenticated or not—must be made over HTTPS. We use the [OAuth 2.0 protocol](http://tools.ietf.org/html/draft-ietf-oauth-v2-31) for API authentication, but only certain portions of the specification. For instance, we only support the use of bearer tokens as access tokens. The specification is a little dense on the standards-speak, but we encourage you to take a look. We'll explain our specific use of OAuth 2 in this document. +All requests to the API—authenticated or not—must be made over HTTPS. We use the [OAuth 2.0 protocol](http://tools.ietf.org/html/rfc6749) for API authentication, but only certain portions of the specification. For instance, we only support the use of bearer tokens as access tokens. The specification is a little dense on the standards-speak, but we encourage you to take a look. We'll explain our specific use of OAuth 2 in this document. ## Initial Developer Setup -Once you have signed up as a developer, you will be able to create an app from the [App.net developer dashboard](https://account.app.net/developer/apps/). You will need to pre-register a **redirection URI**. This is where we will redirect users after they have successfully authorized your application. +Before you begin, make sure you've [created an app](/docs/guides/create-an-app/) in your [App.net developer dashboard](https://account.app.net/developer/apps/). Once you have created an application, you will be assigned a **client ID** and **client secret**. You will use these in the authentication flow. The client ID may be publicly shared (e.g., included in a compiled binary or in the source code of a web page), but the client secret **must** be kept confidential. +You will also need to register a **Redirect URI** with App.net. This is where we will redirect users after they have successfully authorized your application. + It should go without saying, but for the sake of user privacy and security, please ensure that your App.net account has a **strong password**. ## Access Tokens -You authenticate to our API by use of an **access token**. There are two types of access tokens: _app_ tokens and _user_ tokens. **App tokens** (referred to as "client tokens" in the [OAuth 2.0 internet-draft](http://tools.ietf.org/html/draft-ietf-oauth-v2-31)) represent access to API resources on behalf of the application and **user tokens** represent access to API resources on behalf of a specific user. Some resources are only accessible to app or user tokens. +You authenticate to our API by use of an **access token**. There are two types of access tokens: _app_ tokens and _user_ tokens. **App tokens** (referred to as "client tokens" in the [OAuth 2.0 standard](http://tools.ietf.org/html/rfc6749)) represent access to API resources on behalf of the application and **user tokens** represent access to API resources on behalf of a specific user. Some resources are only accessible to app or user tokens.

      Only Apps created by a developer account can request access tokens for other App.net users. If you do not have a developer account, then your app can only be used with your own account. If you ever downgrade your developer account, all current tokens for your app will still work but no new users will be able to authorize it.

      -## How do I get an access token? - -
      -

      We changed the base domain that we use for the authentication flow from alpha.app.net to account.app.net. The old URLs will continue to work forever.

      -
      - -**To obtain a user token**, you must use one of these flows: - -* **[Web flow (server-side)](/reference/authentication/flows/web/#server-side-flow)** - use this if you're building a web application backed by a server. (The OAuth 2.0 internet-draft calls this the [Authorization Code Flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1).) -* **[Web flow (client-side)](/reference/authentication/flows/web/#client-side-flow)** - use this if you're building an application without a central server, like a mobile app or a client-side Javascript app. (The OAuth 2.0 internet-draft calls this the [Implicit Grant Flow](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.2).) -* **[Native App SDK flow](/reference/authentication/flows/sdk/)** - use this if you're building an iOS or Android client. We provide an SDK that you can integrate into your app to streamline authentication. -* **[Password flow](/reference/authentication/flows/password/)** - use this if you're building a native application (or an application where it is difficult to use a web browser) and want to avoid implementing a web-based authentication flow. This flow requires special permission to use and comes with a bunch of extra rules and requirements to protect user security. - -
      -

      If you're submitting your application to one of Apple's App Stores, we suggest you implement authentication via the Native App SDK flow or it's possible your app will be rejected.

      -
      - -**To obtain an app token**, you must use the **[app access token flow](/reference/authentication/flows/app-access-token)**. (The OAuth 2.0 internet-draft calls this this [Client Credentials Grant](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.4).) - -We also intend to provide a SDK you can embed into your mobile applications to provide seamless authentication with App.net to your application's users. - -### Errors - -If an error occurs while obtaining an access token, we'll notify you by redirecting the user to the **Redirection URI** with the following additional query string or fragment parameters: +## What kind of token do I need? -* `error` — a single error code from [this list](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1.2.1) -* `error_description` — a human readable error description. -* `error_uri` — a URI identifying a human-readable webpage with information about the error. +Each endpoint specifies the kind of token it needs: -If a user is redirected to your application with an error code, you should be sure to give your user an informative error message. +* None: no access token is required +* User: a [user token](/reference/authentication/#how-do-i-get-an-access-token) is required. +* App: an [app token](/reference/authentication/flows/app-access-token/) is required. +* Any: either a user token or an app token may be provided but you must have a token of some kind. +* Varies: Authentication may not be required but if it is not provided, you may not be allowed to see a specific resource. For instance, the [Retrieve a Channel](/reference/resources/channel/lookup/#retrieve-a-channel) endpoint allows unauthenticated calls. But if you try to retrieve a Channel that is not marked public, the call will fail. ### Scopes -Scopes are how an application specifies what kind of data it wants from a User. They are specified on the initial access token request. A user will be able to see a list of the permissions you are requesting with explanations of what each of the permissions means. They will be able to authorize any permissions they choose. Your app should not assume that an access token has all the requested scopes. +Scopes let you specify what data your App wants from a User. They do not apply to app tokens. Scopes are specified on the initial access token request. A user will be able to see a list of the scopes you are requesting with explanations of what each of the scopes means. Your app should not assume that an access token has all the requested scopes. When using an OAuth token, App.net will include an extra HTTP headers so the app knows what scopes that token has authorized. For example: @@ -80,11 +61,35 @@ Here is the current list of scopes on App.net: * **files**: manage a user's files. This is not needed for uploading files. * **export**: bulk export all of this user's App.net data. This is intended only for backup services, not day-to-day App.net client use. Users will be shown an extra warning when this scope is requested due to the sensitivity of this data. -The **basic** scope will always be granted on creation of access token, even if the token request omits it. +The **basic** scope will always be granted on creation of a user access token, even if the token request omits it. -## Making Authenticated API Requests +## How do I get an access token? -All requests to the API—authenticated or not—must be made over HTTPS. +### User Token + +* **[Web flow (server-side)](/reference/authentication/flows/web/#server-side-flow)** - use this if you're building a web application backed by a server. (The OAuth 2.0 standard calls this the [Authorization Code Grant](http://tools.ietf.org/html/rfc6749#section-4.1).) +* **[Web flow (client-side)](/reference/authentication/flows/web/#client-side-flow)** - use this if you're building an application without a central server, like a mobile app or a client-side Javascript app. (The OAuth 2.0 standard calls this the [Implicit Grant](http://tools.ietf.org/html/rfc6749#section-4.2).) +* **[Native App SDK flow](/reference/authentication/flows/sdk/)** - use this if you're building an iOS or Android client. We provide an SDK that you can integrate into your app to streamline authentication. +* **[Password flow](/reference/authentication/flows/password/)** - use this if you're building a native application (or an application where it is difficult to use a web browser) and want to avoid implementing a web-based authentication flow. This flow requires special permission to use and comes with a bunch of extra rules and requirements to protect user security. + +
      +

      If you're submitting your application to one of Apple's App Stores, we suggest you implement authentication via the Native App SDK flow or the Password Flow. Otherwise, it's possible your app will be rejected.

      +
      + +### App Token + +**To obtain an app token**, you must use the **[app access token flow](/reference/authentication/flows/app-access-token)**. (The OAuth 2.0 internet-draft calls this this [Client Credentials Grant](http://tools.ietf.org/html/rfc6749#section-4.4).) + +## Errors + +If an error occurs while obtaining an access token, we'll notify you by redirecting the user to the **Redirection URI** with the following additional query string or fragment parameters: + +* `error` — a single error code from [this list](http://tools.ietf.org/html/rfc6749#section-5.2) +* `error_description` — a human readable error description. + +Please ensure your application displays an error message to the user if you receive an error from App.net. + +## Making Authenticated API Requests When making a call to one of our API resources, there are three ways to include authentication information. @@ -117,18 +122,6 @@ When making a call to one of our API resources, there are three ways to include :token => nil }) %> -## What kind of token do I need? - -Each endpoint specified the kind of token it needs: - -* None: no access token is required -* User: a [user token](/reference/authentication/#how-do-i-get-an-access-token) is required. -* App: an [app token](/reference/authentication/flows/app-access-token/) is required. -* Any: either a user token or an app token may be provided but you must have a token of some kind. -* Varies: Authentication may not be required but if it is not provided, you may not be allowed to see a specific resource. For instance, the [Retrieve a Channel](/reference/resources/channel/lookup/#retrieve-a-channel) endpoint allows unauthenticated calls. But if you try to retrieve a Channel that is not marked public, the call will fail. - ## How can I authenticate between App.net apps? -We call this Identity Delegation. The detailed [Identity Delegation -specification](identity-delegation/) has its own page. - +We call this Identity Delegation. The detailed [Identity Delegation specification](identity-delegation/) has its own page. diff --git a/content/reference/index.md b/content/reference/index.md index 93fe96e..6d597a0 100644 --- a/content/reference/index.md +++ b/content/reference/index.md @@ -10,7 +10,7 @@ These pages contain the complete specification of how the App.net API works. We ## Authentication -We use the [OAuth 2.0 protocol](http://tools.ietf.org/html/draft-ietf-oauth-v2-31) to authenticate clients to the API. There are multiple ways to get a token to a user's account. Please read our [Authentication Overview](/reference/authentication/) to choose the right one for your app. +We use the [OAuth 2.0 protocol](http://tools.ietf.org/html/rfc6749) to authenticate clients to the API. There are multiple ways to get a token to a user's account. Please read our [Authentication Overview](/reference/authentication/) to choose the right one for your app. ## Responses From 7363f83f66859cdadc6ca3627a383af610bb27be Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 2 Apr 2014 16:23:07 -0700 Subject: [PATCH 220/231] Clean up oauth errors section --- content/reference/authentication/index.md | 27 +++++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/content/reference/authentication/index.md b/content/reference/authentication/index.md index 1c69abc..d76c97a 100644 --- a/content/reference/authentication/index.md +++ b/content/reference/authentication/index.md @@ -82,13 +82,36 @@ The **basic** scope will always be granted on creation of a user access token, e ## Errors -If an error occurs while obtaining an access token, we'll notify you by redirecting the user to the **Redirection URI** with the following additional query string or fragment parameters: +All OAuth errors will have the following information provided: -* `error` — a single error code from [this list](http://tools.ietf.org/html/rfc6749#section-5.2) +* `error` — a single error code from one of the following lists (depending on which flow you're going through) + * [Errors when requesting an `authorization_code` from the user in the server-side web flow](http://tools.ietf.org/html/rfc6749#section-4.1.2.1) + * [Errors when requesting a token from the user in the client-side web flow](http://tools.ietf.org/html/rfc6749#section-4.2.2.1) + * [Errors when requesting a token from any other flow](http://tools.ietf.org/html/rfc6749#section-5.2) * `error_description` — a human readable error description. +If you're requesting an `authorization_code` from a user in the [server-side web flow](/reference/authentication/flows/web/#server-side-flow) we'll notify you of the error by appending it to your `redirect_uri` as query string parameters. + +If you're requesting a token via the [client-side web flow](/reference/authentication/flows/web/#client-side-flow), we'll append the error to your `redirect_uri` as a URL encoded fragment. + +For all other cases, the error will be returned as JSON in the response to your request. + Please ensure your application displays an error message to the user if you receive an error from App.net. +### Common OAuth Errors + +#### "Please contact the website that sent you here and let them know that there is a problem with the Redirect URI." + +Please make sure that the `redirect_uri` you're passing to App.net is registered for your app in the [Apps dashboard](https://account.app.net/developer/apps/). + +#### "Non-developer apps can only be authorized by their owner." + +This app is owned by an account that isn't a developer account. Remember, apps not owned by a developer account can only authorized the owner of the app. If you believe you have a developer account, please check to make sure [your credit card is correct](https://account.app.net/settings/payment/) and that your account hasn't been downgraded. + +#### "Unknown grant type" + +This often indicates a problem with the encoding of the request you're sending us. Please make sure that you haven't URL encoded the request body multiple times. Also please make sure you're sending your request with a Content-type of `application/x-www-form-urlencoded` not `application/json`. + ## Making Authenticated API Requests When making a call to one of our API resources, there are three ways to include authentication information. From 1b4842080d9921bf0a98a62675ec2551a65d1321 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 2 Apr 2014 16:45:48 -0700 Subject: [PATCH 221/231] Revert "Stop mixing markdown and html, pick one" This reverts commit 12b7337099531a336d84ab9973d0c8a81ec0a477. Conflicts: content/reference/authentication/index.md --- content/reference/authentication/index.md | 3 ++- content/reference/make-request/migrations.md | 2 ++ content/reference/make-request/responses.md | 2 ++ content/reference/resources/place/index.md | 5 ++--- layouts/partials/object-tab.html | 3 ++- 5 files changed, 10 insertions(+), 5 deletions(-) diff --git a/content/reference/authentication/index.md b/content/reference/authentication/index.md index d76c97a..5551e1a 100644 --- a/content/reference/authentication/index.md +++ b/content/reference/authentication/index.md @@ -25,8 +25,9 @@ It should go without saying, but for the sake of user privacy and security, plea You authenticate to our API by use of an **access token**. There are two types of access tokens: _app_ tokens and _user_ tokens. **App tokens** (referred to as "client tokens" in the [OAuth 2.0 standard](http://tools.ietf.org/html/rfc6749)) represent access to API resources on behalf of the application and **user tokens** represent access to API resources on behalf of a specific user. Some resources are only accessible to app or user tokens. +{::options parse_block_html="true" /}
      -

      Only Apps created by a developer account can request access tokens for other App.net users. If you do not have a developer account, then your app can only be used with your own account. If you ever downgrade your developer account, all current tokens for your app will still work but no new users will be able to authorize it.

      +**Note:** Only Apps created by a developer account can request access tokens for other App.net users. If you do not have a developer account, then your app can only be used with your own account. If you ever downgrade your developer account, all current tokens for your app will still work but no new users will be able to authorize it.
      ## What kind of token do I need? diff --git a/content/reference/make-request/migrations.md b/content/reference/make-request/migrations.md index 0454729..2168536 100644 --- a/content/reference/make-request/migrations.md +++ b/content/reference/make-request/migrations.md @@ -9,6 +9,8 @@ title: "Migrations" We reserve the right to make incremental changes to the API as we deem necessary. In order to make it possible to change the API but still support legacy applications, we will make use of migrations. Migrations are a per-app feature that developers may toggle for their own apps from the time that the old behavior is deprecated until the time that it has reached the end of its life (EOL). Once the EOL date is reached, the migration will be enabled for all apps with no legacy mode available. +{::options parse_block_html="true" /} + ## Accessing Migration Data We offer a single toggle for each migration and app that will globally turn the migration on (current mode) or off (legacy mode) for that app as well as a per-call header mechanism that overrides the global behavior. diff --git a/content/reference/make-request/responses.md b/content/reference/make-request/responses.md index abe8dbc..704ba13 100644 --- a/content/reference/make-request/responses.md +++ b/content/reference/make-request/responses.md @@ -11,6 +11,8 @@ All responses to requests to the App.net API endpoints listed under [Resources]( *Please note: the [authentication endpoints](/reference/authentication) return a slightly different format that follows the OAuth2 specification.* +{::options parse_block_html="true" /} + ## Response Envelope The top-level response is an object containing two keys. The first key, `data`, corresponds to the actual response item requested. This may either be an object itself or a list of objects. The particular data returned is described in each endpoint's documentation. If the request is unsuccessful (results in an error), no `data` key will be present. diff --git a/content/reference/resources/place/index.md b/content/reference/resources/place/index.md index 4d29fab..94293f5 100644 --- a/content/reference/resources/place/index.md +++ b/content/reference/resources/place/index.md @@ -162,10 +162,9 @@ Performs a search for nearest places from given latitude and longitude. Optional Returns a list of Places sorted by distance or distance/string match if `q` is provided. These are the same Place objects as returned by the previous endpoint but will also include a `distance` property which gives, in meters, the distance from the search centroid to the Place. +{::options parse_block_html="true" /}
      -

      When using this endpoint, all requests originate from user actions. As an example, acceptable use cases include when a user presses a button to search for local Places or when a user types a character to specify part of a Place name. Unacceptable use cases include automated access (e.g. "bots", "scrapers"), periodic scans and attempts to create comprehensive local caches or copies of the Place data.

      - -

      We will be monitoring search usage and will take necessary actions to terminate unacceptable use.

      +**When using this endpoint, it is a requirement that _all_ requests originate from user actions.** As an example, acceptable use cases include when a user presses a button to search for local Places or when a user types a character to specify part of a Place name. Unacceptable use cases include automated access (e.g. "bots", "scrapers"), periodic scans and attempts to create comprehensive local caches or copies of the Place data. **We will be monitoring search usage and will take necessary actions to terminate unacceptable use.**
      <%= endpoint "GET", "places/search", "User" %> diff --git a/layouts/partials/object-tab.html b/layouts/partials/object-tab.html index 197c5ea..a4a2e8c 100644 --- a/layouts/partials/object-tab.html +++ b/layouts/partials/object-tab.html @@ -3,4 +3,5 @@
    • Endpoints
    -
    +{::options parse_block_html="true" /} +
    \ No newline at end of file From 35c053cd4127c5b4fcb57d0b38d171e54481e28b Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Wed, 2 Apr 2014 16:54:49 -0700 Subject: [PATCH 222/231] put TOCs back where needed --- content/docs/guides/create-a-post.md | 3 --- content/docs/guides/create-an-app.md | 3 --- content/docs/guides/messaging.md | 3 --- content/docs/guides/send-a-broadcast.md | 3 --- content/docs/libraries.md | 3 --- content/reference/index.md | 3 --- static/css/style.css | 1 - 7 files changed, 19 deletions(-) diff --git a/content/docs/guides/create-a-post.md b/content/docs/guides/create-a-post.md index 6ab2d41..bbe807a 100644 --- a/content/docs/guides/create-a-post.md +++ b/content/docs/guides/create-a-post.md @@ -8,9 +8,6 @@ title: "Create a Post" A [Post](/reference/resources/post) is the microblogging primitive of the App.net API. When a user creates a post, it appears in all of their follower's streams. Posts can have images, links, and annotations but at their simplest, they just contain a piece of text. -* TOC -{:toc} - ## Create a post The easiest way to create a post is to use [one of the API libraries](/docs/libraries). diff --git a/content/docs/guides/create-an-app.md b/content/docs/guides/create-an-app.md index 07f6673..48813ad 100644 --- a/content/docs/guides/create-an-app.md +++ b/content/docs/guides/create-an-app.md @@ -6,9 +6,6 @@ title: "Create an App" To start accessing parts of the API that require authentication you will need an **access token**. The easiest way to create an access token is to register an app in your [account dashboard](https://account.app.net/settings/). -* TOC -{:toc} - ## Creating an App 1. Start by visiting [account.app.net/settings/](https://account.app.net/settings/). Click on "[Your Apps](https://account.app.net/developer/apps/)" in the bottom left hand corner to go to Your Apps Dashboard. diff --git a/content/docs/guides/messaging.md b/content/docs/guides/messaging.md index a2f2adf..3c9a1cf 100644 --- a/content/docs/guides/messaging.md +++ b/content/docs/guides/messaging.md @@ -4,9 +4,6 @@ title: "Messaging Overview" # App.net Messaging -* TOC -{:toc} - The App.net Messaging API allows a User to create public, private, semi-private messages between an arbitrary number of users. If you'd like to create public messages that your App.net followers see in their streams, you should [create a post](/reference/resources/post/lifecycle/#create-a-post) with the Stream API. If you need a more flexible messaging solution, the Messaging API is for you. Our messaging API is built around 2 central objects: [Channels](/reference/resources/channel/) and [Messages](/reference/resources/message/). If you're familiar with the App.net Stream API, here are some analogies: diff --git a/content/docs/guides/send-a-broadcast.md b/content/docs/guides/send-a-broadcast.md index b5c6df0..a00352c 100644 --- a/content/docs/guides/send-a-broadcast.md +++ b/content/docs/guides/send-a-broadcast.md @@ -10,9 +10,6 @@ Broadcast Channels are designed to carry low-volume, high-value updates of inter Just a reminder: while you can do all of this using our API, you don't have to. We have [tools for publishers](https://broadcast.app.net/manage/) to help you quickly get started pulling content in from elsewhere on the web, and you can send them manually via the web or the App.net iOS and Android apps. To get started, **we recommend that you create and set up your broadcast channel with [our web publisher tools](https://broadcast.app.net/manage/)** and only use the API to send broadcasts via the channel you created. -* TOC -{:toc} - ## Send a Broadcast There are a number of parts to each broadcast message. To illustrate, here's a screenshot of a broadcast in the App.net iOS app: diff --git a/content/docs/libraries.md b/content/docs/libraries.md index 5dfc2d5..2a5d75a 100644 --- a/content/docs/libraries.md +++ b/content/docs/libraries.md @@ -6,9 +6,6 @@ title: "API Libraries" Using one of the following libraries will help you get up and running with the App.net API in no time. Most of these libraries are maintained by the community. -* TOC -{:toc} - ## Python pip install adnpy diff --git a/content/reference/index.md b/content/reference/index.md index 6d597a0..b6914d4 100644 --- a/content/reference/index.md +++ b/content/reference/index.md @@ -5,9 +5,6 @@ title: "App.net API Reference" These pages contain the complete specification of how the App.net API works. We try to follow standard practices to make our API easy to use from one of our [client libraries](/docs/libraries/) or from any normal HTTP client. -* TOC -{:toc} - ## Authentication We use the [OAuth 2.0 protocol](http://tools.ietf.org/html/rfc6749) to authenticate clients to the API. There are multiple ways to get a token to a user's account. Please read our [Authentication Overview](/reference/authentication/) to choose the right one for your app. diff --git a/static/css/style.css b/static/css/style.css index 6562373..60352d2 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -151,7 +151,6 @@ code { } #markdown-toc { - display: none; color: #ddd; margin: 0 0 30px 0; padding: 10px 0 0 25px; From 03bf38693c126570ba7665fcd385b3eabdceb3e9 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 2 Apr 2014 16:59:14 -0700 Subject: [PATCH 223/231] Get rid of options without breaking everything --- Rules | 2 +- content/reference/authentication/index.md | 3 +-- content/reference/make-request/migrations.md | 2 -- content/reference/make-request/responses.md | 2 -- content/reference/resources/place/index.md | 5 +++-- layouts/partials/object-tab.html | 3 +-- 6 files changed, 6 insertions(+), 11 deletions(-) diff --git a/Rules b/Rules index 08d08df..5f11a25 100644 --- a/Rules +++ b/Rules @@ -29,7 +29,7 @@ compile '*' do # don’t filter binary items else filter :erb - filter :kramdown, :toc_levels => [2], :enable_coderay => false + filter :kramdown, :toc_levels => [2], :enable_coderay => false, :parse_block_html => true filter :colorize_syntax, :default_colorizer => :pygmentsrb, :linenos => 'inline' layout 'default' end diff --git a/content/reference/authentication/index.md b/content/reference/authentication/index.md index 5551e1a..d76c97a 100644 --- a/content/reference/authentication/index.md +++ b/content/reference/authentication/index.md @@ -25,9 +25,8 @@ It should go without saying, but for the sake of user privacy and security, plea You authenticate to our API by use of an **access token**. There are two types of access tokens: _app_ tokens and _user_ tokens. **App tokens** (referred to as "client tokens" in the [OAuth 2.0 standard](http://tools.ietf.org/html/rfc6749)) represent access to API resources on behalf of the application and **user tokens** represent access to API resources on behalf of a specific user. Some resources are only accessible to app or user tokens. -{::options parse_block_html="true" /}
    -**Note:** Only Apps created by a developer account can request access tokens for other App.net users. If you do not have a developer account, then your app can only be used with your own account. If you ever downgrade your developer account, all current tokens for your app will still work but no new users will be able to authorize it. +

    Only Apps created by a developer account can request access tokens for other App.net users. If you do not have a developer account, then your app can only be used with your own account. If you ever downgrade your developer account, all current tokens for your app will still work but no new users will be able to authorize it.

    ## What kind of token do I need? diff --git a/content/reference/make-request/migrations.md b/content/reference/make-request/migrations.md index 2168536..0454729 100644 --- a/content/reference/make-request/migrations.md +++ b/content/reference/make-request/migrations.md @@ -9,8 +9,6 @@ title: "Migrations" We reserve the right to make incremental changes to the API as we deem necessary. In order to make it possible to change the API but still support legacy applications, we will make use of migrations. Migrations are a per-app feature that developers may toggle for their own apps from the time that the old behavior is deprecated until the time that it has reached the end of its life (EOL). Once the EOL date is reached, the migration will be enabled for all apps with no legacy mode available. -{::options parse_block_html="true" /} - ## Accessing Migration Data We offer a single toggle for each migration and app that will globally turn the migration on (current mode) or off (legacy mode) for that app as well as a per-call header mechanism that overrides the global behavior. diff --git a/content/reference/make-request/responses.md b/content/reference/make-request/responses.md index 704ba13..abe8dbc 100644 --- a/content/reference/make-request/responses.md +++ b/content/reference/make-request/responses.md @@ -11,8 +11,6 @@ All responses to requests to the App.net API endpoints listed under [Resources]( *Please note: the [authentication endpoints](/reference/authentication) return a slightly different format that follows the OAuth2 specification.* -{::options parse_block_html="true" /} - ## Response Envelope The top-level response is an object containing two keys. The first key, `data`, corresponds to the actual response item requested. This may either be an object itself or a list of objects. The particular data returned is described in each endpoint's documentation. If the request is unsuccessful (results in an error), no `data` key will be present. diff --git a/content/reference/resources/place/index.md b/content/reference/resources/place/index.md index 94293f5..8db5f48 100644 --- a/content/reference/resources/place/index.md +++ b/content/reference/resources/place/index.md @@ -162,9 +162,10 @@ Performs a search for nearest places from given latitude and longitude. Optional Returns a list of Places sorted by distance or distance/string match if `q` is provided. These are the same Place objects as returned by the previous endpoint but will also include a `distance` property which gives, in meters, the distance from the search centroid to the Place. -{::options parse_block_html="true" /}
    -**When using this endpoint, it is a requirement that _all_ requests originate from user actions.** As an example, acceptable use cases include when a user presses a button to search for local Places or when a user types a character to specify part of a Place name. Unacceptable use cases include automated access (e.g. "bots", "scrapers"), periodic scans and attempts to create comprehensive local caches or copies of the Place data. **We will be monitoring search usage and will take necessary actions to terminate unacceptable use.** +

    When using this endpoint, it is a requirement that all requests originate from user actions. As an example, acceptable use cases include when a user presses a button to search for local Places or when a user types a character to specify part of a Place name. Unacceptable use cases include automated access (e.g. "bots", "scrapers"), periodic scans and attempts to create comprehensive local caches or copies of the Place data.

    + +

    We will be monitoring search usage and will take necessary actions to terminate unacceptable use.

    <%= endpoint "GET", "places/search", "User" %> diff --git a/layouts/partials/object-tab.html b/layouts/partials/object-tab.html index a4a2e8c..197c5ea 100644 --- a/layouts/partials/object-tab.html +++ b/layouts/partials/object-tab.html @@ -3,5 +3,4 @@
  • Endpoints
    • -{::options parse_block_html="true" /} -
    \ No newline at end of file +
    From df83435711a037ba54ae74fb8c3614a034374863 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 2 Apr 2014 17:13:09 -0700 Subject: [PATCH 224/231] Fix front page, can't do this globally --- Rules | 2 +- layouts/partials/object-tab.html | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/Rules b/Rules index 5f11a25..08d08df 100644 --- a/Rules +++ b/Rules @@ -29,7 +29,7 @@ compile '*' do # don’t filter binary items else filter :erb - filter :kramdown, :toc_levels => [2], :enable_coderay => false, :parse_block_html => true + filter :kramdown, :toc_levels => [2], :enable_coderay => false filter :colorize_syntax, :default_colorizer => :pygmentsrb, :linenos => 'inline' layout 'default' end diff --git a/layouts/partials/object-tab.html b/layouts/partials/object-tab.html index 197c5ea..a1c7345 100644 --- a/layouts/partials/object-tab.html +++ b/layouts/partials/object-tab.html @@ -3,4 +3,5 @@
  • Endpoints
    • +{::options parse_block_html="true" /}
    From 5a236839cd33cb1b7bb1384b2153e6cbd51326b5 Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Wed, 2 Apr 2014 17:31:12 -0700 Subject: [PATCH 225/231] anchor links! --- content/assets/js/app.js | 7 +++++++ static/css/style.css | 25 +++++++++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/content/assets/js/app.js b/content/assets/js/app.js index b5ebdf2..c791bd7 100644 --- a/content/assets/js/app.js +++ b/content/assets/js/app.js @@ -62,4 +62,11 @@ $(function() { el.html(el.html().replace(needle, token.user_token)); }); }); + + $(".content h1, .content h2, .content h3, .content h4").each(function(e){ + var id = $(this).attr("id"); + if (!id) return; + + $(this).append(""); + }); }); diff --git a/static/css/style.css b/static/css/style.css index 60352d2..21e7e2e 100644 --- a/static/css/style.css +++ b/static/css/style.css @@ -202,6 +202,7 @@ ul.nav-list { padding: 0 0 20px 0; -webkit-font-smoothing: subpixel-antialiased; border: none; + width: auto; } ul.nav-list li { @@ -368,3 +369,27 @@ html.breakpoint-retina .promo-block-image.authentication { margin-left:auto; *zoom:1 } + +.header-anchor { + top: 0; + opacity: 0; + padding: 0 5px 0 10px; + height: 100%; + width: 20px; + font-size: 12px; + font-weight: normal; + -webkit-font-smoothing: antialiased; + + -webkit-transition: opacity 0.3s ease-in-out 0s; + -moz-transition: opacity 0.3s ease-in-out 0s; + -ms-transition: opacity 0.3s ease-in-out 0s; +} + +.content h1:hover .header-anchor, .content h2:hover .header-anchor, .content h3:hover .header-anchor, .content h4:hover .header-anchor, .header-anchor:hover { + opacity: 1; + text-decoration: none; +} + +.header-anchor:before { + content:'#'; +} From a98427cf521ee38a851665811201aab3b476553d Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 2 Apr 2014 17:42:58 -0700 Subject: [PATCH 226/231] Search supports pagination --- content/reference/resources/channel/search.md | 4 +++- content/reference/resources/message/search.md | 6 ++++-- content/reference/resources/post/search.md | 6 ++++-- 3 files changed, 11 insertions(+), 5 deletions(-) diff --git a/content/reference/resources/channel/search.md b/content/reference/resources/channel/search.md index bd407a9..3547da1 100644 --- a/content/reference/resources/channel/search.md +++ b/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. net.patter-app.settings. 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 messages 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 or messages" %> diff --git a/content/reference/resources/message/search.md b/content/reference/resources/message/search.md index e790371..207ade1 100644 --- a/content/reference/resources/message/search.md +++ b/content/reference/resources/message/search.md @@ -11,7 +11,9 @@ title: "Message Search" Returns [Message](/reference/resources/message/) objects which match a given search query. This endpoint responds to a list of channel IDs which can either given specifically or performed on all PM or Broadcast channels that the user is subscribed to. Searches can either be ordered by `id` or `score`. Searches ordered by `id` require at least one query or filter to be specified; searches ordered by `score` require at least one query and zero or more filters to be specified. All parameters should be passed in the query string. -<%= general_params_note_for "message" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Separate lists of terms by spaces. +All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Separate lists of terms by spaces. + +<%= general_params_note_for "message" %> <%= endpoint "GET", "channels/messages/search", "Any" %> @@ -19,7 +21,7 @@ Returns [Message](/reference/resources/message/) objects which match a given sea ["index", :optional, "string", "Type of index to use. The default (and currently, the only) index is complete, which searches all messages. We may add additional index types later (e.g., an index only of recent messages, for speed.)"], - ["order", :optional, "string", "One of: id (default), score. Searches of ordering id are returned in roughly the same order as other streams, and support pagination. Searches of ordering score are returned by a relevance score. Currently, the only ordering that supports pagination is id, and we are working on improving relevance scores."], + ["order", :optional, "string", "One of: id (default), score. Searches of ordering id are returned in roughly the same order as other streams. Searches of ordering score are returned by a relevance score."], ]%> diff --git a/content/reference/resources/post/search.md b/content/reference/resources/post/search.md index d706e6d..6015ed3 100644 --- a/content/reference/resources/post/search.md +++ b/content/reference/resources/post/search.md @@ -11,7 +11,9 @@ title: "Post Search" Returns [Post](/reference/resources/post/) objects which match a given search query. Searches ordered by `id` require at least one query or filter to be specified; searches ordered by `score` require at least one query and zero or more filters to be specified. Searches require an ordering and at least one search query to be specified, and allow for zero or more filters to be added. All parameters should be passed in the query string. -<%= general_params_note_for "post" %> Note: Pagination is currently only available for the `id` ordering. All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. Separate lists of terms by spaces. +All queries and filters are combined with an AND operation. Query parameters (not filter parameters) can use "quoted strings" for phrases, search syntax like +foo -bar and foo OR baz for boolean queries. Machine-only posts are not included in the search index. Separate lists of terms by spaces. + +<%= general_params_note_for "post" %> <%= endpoint "GET", "posts/search", "Any" %> @@ -19,7 +21,7 @@ Returns [Post](/reference/resources/post/) objects which match a given search qu ["index", :optional, "string", "Type of index to use. The default (and currently, the only) index is complete, which searches all posts. We may add additional index types later (e.g., an index only of recent posts, for speed.)"], - ["order", :optional, "string", "One of: id (default), score. Searches of ordering id are returned in roughly the same order as other streams, and support pagination. Searches of ordering score are returned by a relevance score. Currently, the only ordering that supports pagination is id, and we are working on improving relevance scores."], + ["order", :optional, "string", "One of: id (default), score. Searches of ordering id are returned in roughly the same order as other streams. Searches of ordering score are returned by a relevance score."], ]%> From 7ba49bf855f375e3d880f63100a06825c5e6263d Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Wed, 2 Apr 2014 17:49:13 -0700 Subject: [PATCH 227/231] 'Note:' is almost always redundant --- content/reference/authentication/flows/app-access-token.md | 2 +- content/reference/authentication/flows/web.md | 2 +- content/reference/authentication/index.md | 2 +- content/reference/make-request/responses.md | 4 ++-- content/reference/meta/entities.md | 2 +- content/reference/other/feeds.md | 2 +- content/reference/other/web-intents.md | 2 +- content/reference/resources/file/index.md | 2 +- content/reference/resources/interaction/index.md | 6 +++--- content/reference/resources/message/lifecycle.md | 2 +- content/reference/resources/message/lookup.md | 2 +- content/reference/resources/post/lifecycle.md | 2 +- content/reference/resources/post/reposts.md | 2 +- content/reference/resources/post/stars.md | 2 +- content/reference/resources/user/muting.md | 2 +- lib/helpers.rb | 2 +- 16 files changed, 19 insertions(+), 19 deletions(-) diff --git a/content/reference/authentication/flows/app-access-token.md b/content/reference/authentication/flows/app-access-token.md index 811ed8a..1d26c52 100644 --- a/content/reference/authentication/flows/app-access-token.md +++ b/content/reference/authentication/flows/app-access-token.md @@ -19,7 +19,7 @@ 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). +> 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: diff --git a/content/reference/authentication/flows/web.md b/content/reference/authentication/flows/web.md index 0f06029..7eeaa19 100644 --- a/content/reference/authentication/flows/web.md +++ b/content/reference/authentication/flows/web.md @@ -45,7 +45,7 @@ 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). + > 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...}}` diff --git a/content/reference/authentication/index.md b/content/reference/authentication/index.md index d76c97a..464ecb7 100644 --- a/content/reference/authentication/index.md +++ b/content/reference/authentication/index.md @@ -137,7 +137,7 @@ When making a call to one of our API resources, there are three ways to include * 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" => ""}, diff --git a/content/reference/make-request/responses.md b/content/reference/make-request/responses.md index abe8dbc..da5915c 100644 --- a/content/reference/make-request/responses.md +++ b/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 diff --git a/content/reference/meta/entities.md b/content/reference/meta/entities.md index 5e1fa04..c35f417 100644 --- a/content/reference/meta/entities.md +++ b/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. -
    Note: pos and len 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.
    +
    pos and len 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.
    All of the following examples are about the following text: diff --git a/content/reference/other/feeds.md b/content/reference/other/feeds.md index 81a8788..12ea2ed 100644 --- a/content/reference/other/feeds.md +++ b/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 diff --git a/content/reference/other/web-intents.md b/content/reference/other/web-intents.md index d8ecace..d98dcb8 100644 --- a/content/reference/other/web-intents.md +++ b/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
    -

    Note: If you just want a simple follow or share button you can use button builder instead. We've also open sourced the buttons so that you could host them your self. Checkout the github repo for more information on how to do that.

    +

    If you just want a simple follow or share button you can use button builder instead. We've also open sourced the buttons so that you could host them your self. Checkout the github repo for more information on how to do that.

    ## The Post Intent diff --git a/content/reference/resources/file/index.md b/content/reference/resources/file/index.md index bd6577e..f90024d 100644 --- a/content/reference/resources/file/index.md +++ b/content/reference/resources/file/index.md @@ -200,7 +200,7 @@ Derived files will include the keys shown in the example below. Please see [the ### Auto-generated derived files -For some files, App.net will auto generate derived files. *Note: any new auto-generated derived file keys will be prefixed with `core_`.* +For some files, App.net will auto generate derived files. *Any new auto-generated derived file keys will be prefixed with `core_`.* * `image_thumb_200s`: When the root file is an image, App.net will generate a 200x200 square thumbnail of the image that shrinks and crops the center square of the image. * `image_thumb_960r`: When the root file is an image, App.net will scale down the entire image so it fits within a 640x960 pixel bounding box. This thumbnail will not be cropped. diff --git a/content/reference/resources/interaction/index.md b/content/reference/resources/interaction/index.md index 703447a..5534d1d 100644 --- a/content/reference/resources/interaction/index.md +++ b/content/reference/resources/interaction/index.md @@ -9,7 +9,7 @@ title: "Interactions" Interactions are objects that represent users taking certain actions on App.net. Interactions are structured to form a sentence like: User X took action Y on object Z. If multiple users take the same action (e.g. multiple users reply to one post) within a set time window those events will be combined into a single Interaction. -> Note: the `objects` list of an Interaction will vary based on the `action` +> The `objects` list of an Interaction will vary based on the `action` (Example) @dalton and @berg reposted post 1: @@ -59,10 +59,10 @@ List all the [Interactions](/reference/resources/interaction/) other users have <%= pagination_note %> -> Note: you can only request this list for the current user. +> You can only request this list for the current user. -> Note: although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/reference/resources/app-stream/) to monitor the global feed for relevant activity. +> Although this endpoint supports paging, a user's Interactions stream is continuously rebuilt as new actions in the system occur, so developers should generally plan to refetch the stream whenever switching to display it as Interactions may have shifted their position, with users being added or removed. If you need to keep track of activity in a more precise manner, you should using the [Streaming API](/reference/resources/app-stream/) to monitor the global feed for relevant activity. This endpoint accepts the `interaction_actions` as a query string parameter whose value is a comma separated list of actions you're interested in. For instance, if you're only interested in repost and follow interactions you could request `stream/0/users/me/interactions?interaction_actions=repost,follow`. diff --git a/content/reference/resources/message/lifecycle.md b/content/reference/resources/message/lifecycle.md index b6c8934..b109bfa 100644 --- a/content/reference/resources/message/lifecycle.md +++ b/content/reference/resources/message/lifecycle.md @@ -52,7 +52,7 @@ end %> Delete a message. The current user must be the same user who created the Message. It returns the deleted Message on success. -*Note: you can always delete a message you created even if you are no longer able to view the rest of the Channel anymore.* +*You can always delete a message you created even if you are no longer able to view the rest of the Channel anymore.* *Remember, access tokens can not be passed in a HTTP body for `DELETE` requests. Please refer to the [authentication documentation](/reference/authentication/#making-authenticated-api-requests).* diff --git a/content/reference/resources/message/lookup.md b/content/reference/resources/message/lookup.md index ff7585f..e5dfabf 100644 --- a/content/reference/resources/message/lookup.md +++ b/content/reference/resources/message/lookup.md @@ -11,7 +11,7 @@ title: "Message Lookup" Returns a specific [Message](/reference/resources/message/). -*Note: you can always retrieve a message you created even if you are no longer able to view the rest of the Channel anymore.* +*You can always retrieve a message you created even if you are no longer able to view the rest of the Channel anymore.* <%= general_params_note_for "message" %> diff --git a/content/reference/resources/post/lifecycle.md b/content/reference/resources/post/lifecycle.md index 21610b4..13777e1 100644 --- a/content/reference/resources/post/lifecycle.md +++ b/content/reference/resources/post/lifecycle.md @@ -15,7 +15,7 @@ You can also create a Post by sending JSON in the HTTP post body that matches th If you want to test how your text will be processed you can use the [text processor](/reference/resources/text-processor). -*Note: You cannot reply to a repost. Please reply to the parent Post.* +*You cannot reply to a repost. Please reply to the parent Post.* <%= general_params_note_for "post" %> diff --git a/content/reference/resources/post/reposts.md b/content/reference/resources/post/reposts.md index 4f044b7..18edfcd 100644 --- a/content/reference/resources/post/reposts.md +++ b/content/reference/resources/post/reposts.md @@ -33,7 +33,7 @@ end %> ## Unrepost a Post -Given the original `post_id`, delete the current user's repost. *Note: this same functionality can be accomplished by [deleting using the repost's post_id](/reference/resources/post/lifecycle/#delete-a-post)*. +Given the original `post_id`, delete the current user's repost. *This same functionality can be accomplished by [deleting using the repost's post_id](/reference/resources/post/lifecycle/#delete-a-post)*. <%= general_params_note_for "post" %> diff --git a/content/reference/resources/post/stars.md b/content/reference/resources/post/stars.md index 25a1e3e..6cd69ad 100644 --- a/content/reference/resources/post/stars.md +++ b/content/reference/resources/post/stars.md @@ -11,7 +11,7 @@ title: "Stars" Save a given Post to the current User's stars. This is just a "save" action, not a sharing action. A User's stars are visible to others, but they are not automatically added to your followers' streams. -*Note: A repost cannot be starred. Please star the parent Post.* +*A repost cannot be starred. Please star the parent Post.* <%= general_params_note_for "post" %> diff --git a/content/reference/resources/user/muting.md b/content/reference/resources/user/muting.md index 6fb07f1..e1f4158 100644 --- a/content/reference/resources/user/muting.md +++ b/content/reference/resources/user/muting.md @@ -9,7 +9,7 @@ title: "User Muting" ## Mute a User -Hide all posts for a User in all streams. *Note: if you still explicitly request this User's stream or a Post from this User, it will not be hidden.* +Hide all posts for a User in all streams. *If you still explicitly request this User's stream or a Post from this User, it will not be hidden.* <%= general_params_note_for "user" %> diff --git a/lib/helpers.rb b/lib/helpers.rb index a959a07..8131b84 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -15,7 +15,7 @@ def migration_warning(migrations = []) plur = "" end - "
    Note: This endpoint is currently migrated by the #{ join_all migrations } migration#{ plur }. Please refer to the Migrations documentation for more info.
    " + "
    This endpoint is currently migrated by the #{ join_all migrations } migration#{ plur }. Please refer to the Migrations documentation for more info.
    " end end From 16f80018e2c6fd5d821d7f5c21653159c158d163 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Thu, 3 Apr 2014 10:28:25 -0700 Subject: [PATCH 228/231] Fix issues with bash quoting --- .../authentication/flows/password.md | 4 ++-- content/reference/authentication/index.md | 2 +- content/reference/resources/post/lifecycle.md | 2 +- lib/helpers.rb | 21 +++++++++++-------- 4 files changed, 16 insertions(+), 13 deletions(-) diff --git a/content/reference/authentication/flows/password.md b/content/reference/authentication/flows/password.md index 34ec6d6..6e648bf 100644 --- a/content/reference/authentication/flows/password.md +++ b/content/reference/authentication/flows/password.md @@ -49,9 +49,9 @@ 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. + > 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** irrespective of this parameter. We strongly encourage the use of app-specific passwords by all users as they significantly increase account security. + > **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: diff --git a/content/reference/authentication/index.md b/content/reference/authentication/index.md index 464ecb7..241b4e1 100644 --- a/content/reference/authentication/index.md +++ b/content/reference/authentication/index.md @@ -133,7 +133,7 @@ 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=", :none, {:data => "text=Test post", :content_type => nil, :token => nil}) %> + <%= curl_example(:get, "posts/1?access_token=", :none, {:data => {"text" => "Test post"}, :content_type => nil, :token => nil}) %> * Add `access_token` to HTTP body. diff --git a/content/reference/resources/post/lifecycle.md b/content/reference/resources/post/lifecycle.md index 13777e1..925b6dc 100644 --- a/content/reference/resources/post/lifecycle.md +++ b/content/reference/resources/post/lifecycle.md @@ -29,7 +29,7 @@ If you want to test how your text will be processed you can use the [text proces #### Example <% text = get_hash(:post)["text"] %> -<%= curl_example(:post, "posts", :post, {:data => "text=#{text}", :content_type => nil}) %> +<%= curl_example(:post, "posts", :post, {:data => {"text" => text}, :content_type => nil}) %> #### Example (JSON Data) diff --git a/lib/helpers.rb b/lib/helpers.rb index 8131b84..e154028 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -90,6 +90,10 @@ def access_token_banner() "

    #{login_url} to see more complete examples.

    " end +def bash_quote(v) + v.gsub('"', '\"') +end + def curl_example(method, path, response_key, options = {}, &block) # things left to figure out # - some quoting/escaping stuff @@ -167,24 +171,23 @@ def curl_example(method, path, response_key, options = {}, &block) if [:post, :put, :patch].include? method if not options[:data].empty? if options[:content_type] == "application/json" - options[:data] = JSON.pretty_generate(options[:data]) - # todo: escape any single quotes in json data since we're about to wrap in single quotes for bash - curl_parts << %{-d '#{options[:data]}'} + data = bash_quote(JSON.pretty_generate(options[:data])) + curl_parts << %{-d "#{data}"} elsif options[:data].instance_of? Hash options[:data].each do |k, v| - curl_parts << %{-d '#{k}=#{v}'} + val = bash_quote(v) + curl_parts << %{-d "#{k}=#{val}"} end - else - # get rid of this case - curl_parts << %{-d '#{options[:data]}'} end elsif options[:data_binary] - curl_parts << %{--data-binary '#{options[:data_binary]}'} + val = bash_quote(options[:data_binary]) + curl_parts << %{--data-binary "#{val}"} end end options[:files].each do |k, v| - curl_parts << %{-F "#{k}=#{v}"} + val = bash_quote(v) + curl_parts << %{-F "#{k}=#{val}"} end if options[:stdin] From 8e4bd5093d5272ef16096a2e0bcb9c44f0e8bd8b Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Thu, 3 Apr 2014 11:29:25 -0700 Subject: [PATCH 229/231] Add authorization curl examples And explicitly call out where we need the Content-type header to be application/x-www-form-urlencoded (usually just in authentication). --- .../authentication/flows/app-access-token.md | 16 +++++++ .../authentication/flows/password.md | 18 +++++++ content/reference/authentication/flows/web.md | 17 +++++++ .../authentication/identity-delegation.md | 47 ++++++++++++++++++- lib/helpers.rb | 5 +- 5 files changed, 100 insertions(+), 3 deletions(-) diff --git a/content/reference/authentication/flows/app-access-token.md b/content/reference/authentication/flows/app-access-token.md index 1d26c52..ff5a13e 100644 --- a/content/reference/authentication/flows/app-access-token.md +++ b/content/reference/authentication/flows/app-access-token.md @@ -19,6 +19,22 @@ with URL-encoded POST body: &client_secret=[your client secret] &grant_type=client_credentials +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: diff --git a/content/reference/authentication/flows/password.md b/content/reference/authentication/flows/password.md index 6e648bf..630edbc 100644 --- a/content/reference/authentication/flows/password.md +++ b/content/reference/authentication/flows/password.md @@ -49,6 +49,24 @@ Once you have been approved, using the password flow is pretty straightforward: &password=[user's password] &scope=[scopes separated by spaces] + 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. diff --git a/content/reference/authentication/flows/web.md b/content/reference/authentication/flows/web.md index 7eeaa19..768a6da 100644 --- a/content/reference/authentication/flows/web.md +++ b/content/reference/authentication/flows/web.md @@ -45,6 +45,23 @@ 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] + 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...}}` diff --git a/content/reference/authentication/identity-delegation.md b/content/reference/authentication/identity-delegation.md index b7b605d..d0e0a95 100644 --- a/content/reference/authentication/identity-delegation.md +++ b/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. diff --git a/lib/helpers.rb b/lib/helpers.rb index e154028..d09ebb6 100644 --- a/lib/helpers.rb +++ b/lib/helpers.rb @@ -160,7 +160,10 @@ def curl_example(method, path, response_key, options = {}, &block) end - if [:post, :put, :patch].include? method and options[:content_type] and (options[:data_binary] or not options[:data].empty?) + if [:post, :put, :patch].include? method and (options[:data_binary] or not options[:data].empty?) + unless options[:content_type] + options[:content_type] = "application/x-www-form-urlencoded" + end options[:headers]["Content-Type"] = options[:content_type] end From 883aaa29eb429f7150d0905d0bb9ae876785b1a1 Mon Sep 17 00:00:00 2001 From: Mark Thurman Date: Thu, 3 Apr 2014 11:55:28 -0700 Subject: [PATCH 230/231] Tweak this wording --- content/reference/authentication/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/reference/authentication/index.md b/content/reference/authentication/index.md index 241b4e1..052a8b6 100644 --- a/content/reference/authentication/index.md +++ b/content/reference/authentication/index.md @@ -73,7 +73,7 @@ The **basic** scope will always be granted on creation of a user access token, e * **[Password flow](/reference/authentication/flows/password/)** - use this if you're building a native application (or an application where it is difficult to use a web browser) and want to avoid implementing a web-based authentication flow. This flow requires special permission to use and comes with a bunch of extra rules and requirements to protect user security.
    -

    If you're submitting your application to one of Apple's App Stores, we suggest you implement authentication via the Native App SDK flow or the Password Flow. Otherwise, it's possible your app will be rejected.

    +

    If you're submitting your application to one of Apple's App Stores, you should not use any of the web based flows. We suggest you implement authentication via the Native App SDK flow with the Password Flow as a backup. Otherwise, it's possible your app will be rejected.

    ### App Token From 94d2613d776b791afe9a7f6db21dc3d04b7c1f16 Mon Sep 17 00:00:00 2001 From: Bryan Berg Date: Thu, 3 Apr 2014 23:45:08 -0700 Subject: [PATCH 231/231] / -> /docs/ --- content/docs/index.md | 88 ++++++++++++++++++++++++++++++++++ content/index.md | 89 +---------------------------------- layouts/partials/top_nav.html | 2 +- 3 files changed, 91 insertions(+), 88 deletions(-) create mode 100644 content/docs/index.md diff --git a/content/docs/index.md b/content/docs/index.md new file mode 100644 index 0000000..73f6889 --- /dev/null +++ b/content/docs/index.md @@ -0,0 +1,88 @@ +--- +title: "Home" +--- + +# App.net API Documentation + +App.net is a developer-friendly social infrastructure platform. Our API is the primary interface by which developers interact with the platform. The documentation is broken into two parts: these guides and our [full API reference](/reference/). + +## Quick Start + +The App.net API is powerful and flexible -- if you're new to the API, we suggest you start with these guides. + +
    +
    +
    +
    +
    + +
    +

    + Quick Start: Broadcast
    +

    +

    Send a broadcast with the App.net API.

    +
    +
    +
    +
    +
    +
    + +
    +

    + Quick Start: Authentication
    +

    +

    Learn how to make authenticated requests to the API.

    +
    +
    +
    +
    +
    + +## Notable API features + +### Identity & Authentication + +Use App.net's identity layer to authenticate users and populate user profiles. For more information, see the [Authentication reference](/reference/authentication/) and [User reference](/reference/resources/user/). + +### Social Graph + +App.net has a asymmetrical (follower-following) social graph which can be used to solve the "cold start" problem when a user signs into your app. The [Following reference](/reference/resources/user/following/) has more details. + +### Messaging + +Channels are like chat rooms. They're a time ordered series of messages that can be public, private, or restricted to a group of App.net users. The messages inside of channels can take advantage of App.net files, places, and anything else the API provides. [Chat rooms](https://directory.app.net/app/145/patter/), [Broadcasts](http://blog.app.net/2013/11/21/announcing-app-net-broadcast/), and private messages are all built on top of [App.net Messaging](/docs/guides/messaging/). + +### Places + +App.net has a location database that can be integrated with your app. This allows you to add location to Posts or Message to enable location aware apps. See the [Places reference](/docs/references/resources/places/) for more information. + +### Annotations + +Annotations are machine readable metadata that can be attached to most App.net objects (posts, messages, users, and more). They power [checkins](https://alpha.app.net/browse/checkins/), [photos](https://alpha.app.net/browse/photos/) and other rich posts on App.net. See the [Annotations introduction](/docs/references/resources/meta/annotations/) to get started. + +### Files + +App.net gives each user space to store and share files. These files can be shared publicly, attached to posts, or sent as a private message to a friend. All App.net apps share the same file storage space so if a new photo or video app comes along, you can check it out and not have to worry about migrating all your old data. See the [Files reference](/docs/references/resources/files/) for more information. + + +## Tracking news and announcements + +To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adnapi). You may also want to subscribe to the [App.net blog](https://broadcast.app.net/26283/appnet-blog/) for general news and the [App.net API Updates](https://broadcast.app.net/24368/appnet-api-updates/) Broadcast channel for developer related news. + +## Getting help and providing feedback + +There are numerous ways for developers to get help utilizing the platform and to provide feedback. + +* Developers (including App.net staff) are often chatting in the [Developer Channel](http://patter-app.net/room.html?channel=1383). +* For developer inquiries about the API, our Terms of Service, letting us know about something you're working on, etc., email [developers@app.net](mailto:developers@app.net). +* For general inquiries about account/service related issues, email [support@app.net](mailto:support@app.net). +* In addition to the above, you can report bugs and provide feedback on the API using the [issue tracker](https://github.com/appdotnet/api-spec/issues). +* This documentation is open source. If you find an error or something that's unclear, let us know with a pull request or issue on the [Github repo for the documentation](https://github.com/appdotnet/api-spec/). + +## Your hosts + +* [Bryan Berg](http://ber.gd) ([@berg](https://alpha.app.net/berg), [bryan@app.net](mailto:bryan@app.net)) +* Mark Thurman ([@mthurman](https://alpha.app.net/mthurman), [mthurman@app.net](mailto:mthurman@app.net)) +* [Alex Kessinger](http://alexkessinger.net) ([@voidfiles](https://alpha.app.net/voidfiles), [alex@app.net](mailto:alex@app.net)) +* Brian Armstrong ([@barmstrong](https://alpha.app.net/barmstrong), [barmstrong@app.net](mailto:barmstrong@app.net)) diff --git a/content/index.md b/content/index.md index 73f6889..2b75631 100644 --- a/content/index.md +++ b/content/index.md @@ -1,88 +1,3 @@ ---- -title: "Home" ---- +# Documentation -# App.net API Documentation - -App.net is a developer-friendly social infrastructure platform. Our API is the primary interface by which developers interact with the platform. The documentation is broken into two parts: these guides and our [full API reference](/reference/). - -## Quick Start - -The App.net API is powerful and flexible -- if you're new to the API, we suggest you start with these guides. - -
    -
    -
    -
    -
    - -
    -

    - Quick Start: Broadcast
    -

    -

    Send a broadcast with the App.net API.

    -
    -
    -
    -
    -
    -
    - -
    -

    - Quick Start: Authentication
    -

    -

    Learn how to make authenticated requests to the API.

    -
    -
    -
    -
    -
    - -## Notable API features - -### Identity & Authentication - -Use App.net's identity layer to authenticate users and populate user profiles. For more information, see the [Authentication reference](/reference/authentication/) and [User reference](/reference/resources/user/). - -### Social Graph - -App.net has a asymmetrical (follower-following) social graph which can be used to solve the "cold start" problem when a user signs into your app. The [Following reference](/reference/resources/user/following/) has more details. - -### Messaging - -Channels are like chat rooms. They're a time ordered series of messages that can be public, private, or restricted to a group of App.net users. The messages inside of channels can take advantage of App.net files, places, and anything else the API provides. [Chat rooms](https://directory.app.net/app/145/patter/), [Broadcasts](http://blog.app.net/2013/11/21/announcing-app-net-broadcast/), and private messages are all built on top of [App.net Messaging](/docs/guides/messaging/). - -### Places - -App.net has a location database that can be integrated with your app. This allows you to add location to Posts or Message to enable location aware apps. See the [Places reference](/docs/references/resources/places/) for more information. - -### Annotations - -Annotations are machine readable metadata that can be attached to most App.net objects (posts, messages, users, and more). They power [checkins](https://alpha.app.net/browse/checkins/), [photos](https://alpha.app.net/browse/photos/) and other rich posts on App.net. See the [Annotations introduction](/docs/references/resources/meta/annotations/) to get started. - -### Files - -App.net gives each user space to store and share files. These files can be shared publicly, attached to posts, or sent as a private message to a friend. All App.net apps share the same file storage space so if a new photo or video app comes along, you can check it out and not have to worry about migrating all your old data. See the [Files reference](/docs/references/resources/files/) for more information. - - -## Tracking news and announcements - -To see the latest updates to the API, follow [@adnapi](http://alpha.app.net/adnapi). You may also want to subscribe to the [App.net blog](https://broadcast.app.net/26283/appnet-blog/) for general news and the [App.net API Updates](https://broadcast.app.net/24368/appnet-api-updates/) Broadcast channel for developer related news. - -## Getting help and providing feedback - -There are numerous ways for developers to get help utilizing the platform and to provide feedback. - -* Developers (including App.net staff) are often chatting in the [Developer Channel](http://patter-app.net/room.html?channel=1383). -* For developer inquiries about the API, our Terms of Service, letting us know about something you're working on, etc., email [developers@app.net](mailto:developers@app.net). -* For general inquiries about account/service related issues, email [support@app.net](mailto:support@app.net). -* In addition to the above, you can report bugs and provide feedback on the API using the [issue tracker](https://github.com/appdotnet/api-spec/issues). -* This documentation is open source. If you find an error or something that's unclear, let us know with a pull request or issue on the [Github repo for the documentation](https://github.com/appdotnet/api-spec/). - -## Your hosts - -* [Bryan Berg](http://ber.gd) ([@berg](https://alpha.app.net/berg), [bryan@app.net](mailto:bryan@app.net)) -* Mark Thurman ([@mthurman](https://alpha.app.net/mthurman), [mthurman@app.net](mailto:mthurman@app.net)) -* [Alex Kessinger](http://alexkessinger.net) ([@voidfiles](https://alpha.app.net/voidfiles), [alex@app.net](mailto:alex@app.net)) -* Brian Armstrong ([@barmstrong](https://alpha.app.net/barmstrong), [barmstrong@app.net](mailto:barmstrong@app.net)) +Root of docs is [here](/docs/). diff --git a/layouts/partials/top_nav.html b/layouts/partials/top_nav.html index 939a9df..40a8c5a 100644 --- a/layouts/partials/top_nav.html +++ b/layouts/partials/top_nav.html @@ -2,7 +2,7 @@
  • Documentation