Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Add stars to API Spec

  • Loading branch information...
commit 0fc3d2c4f2d288376bfccd9118d76ccc7f638ce4 1 parent 8af7dfc
@mthurman mthurman authored
View
2  annotations.md
@@ -53,6 +53,7 @@ Here's a sample post with annotations:
"html": "<span itemscope=\"https://app.net/schemas/Post\">first annotation post</span>",
"id": "1",
"num_replies": 0,
+ "num_stars": 0,
"source": {
"link": "https://join.app.net/",
"name": "App.net"
@@ -60,6 +61,7 @@ Here's a sample post with annotations:
"text": "first annotation post",
"thread_id": "1255",
"user": {...}
+ "you_starred": false
}
```
View
24 objects.md
@@ -237,6 +237,7 @@ A Post is the other central object utilized by the App.net Stream API. It has ri
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 1,
"annotations": [
{
"type": "net.app.core.geo",
@@ -264,7 +265,11 @@ A Post is the other central object utilized by the App.net Stream API. It has ri
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false,
+ "starred_by": [
+ ...users...
+ ]
}
```
@@ -342,8 +347,13 @@ A Post is the other central object utilized by the App.net Stream API. It has ri
<td>The number of posts created in reply to this post.</td>
</tr>
<tr>
+ <td><code>num_stars</code></td>
+ <td>integer</td>
+ <td>The number of users who have starred this post.</td>
+ </tr>
+ <tr>
<td><code>annotations</code></td>
- <td>object</td>
+ <td>list</td>
<td>Metadata about the entire post. See the <a href="/appdotnet/api-spec/blob/master/objects.md#annotations">annotations documentation</a>.</td>
</tr>
<tr>
@@ -361,6 +371,16 @@ A Post is the other central object utilized by the App.net Stream API. It has ri
<td>boolean</td>
<td>Is this Post meant for humans or other apps? See <a href="#machine-only-posts">Machine only Posts</a> for more information.</td>
</tr>
+ <tr>
+ <td><code>you_starred</code></td>
+ <td>boolean</td>
+ <td>Have you starred this Post?</td>
+ </tr>
+ <tr>
+ <td><code>starred_by</code></td>
+ <td>list</td>
+ <td>A partial list of users who have starred this post. This is not comprehensive and is meant to be a sample of users who have starred this post giving preference to users the current user follows.</td>
+ </tr>
</table>
#### Deprecations
View
20 resources/README.md
@@ -62,6 +62,11 @@ Please use https://alpha-api.app.net/ to access the APIs.
<td>GET</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/users.md#list-muted-users">List muted users</a></td>
</tr>
+ <tr>
+ <td>/stream/0/posts/[post_id]/stars</td>
+ <td>GET</td>
+ <td><a href="/appdotnet/api-spec/blob/master/resources/users.md#list-users-who-have-starred-a-post">List Users who have starred a Post</a></td>
+ </tr>
</tbody>
</table>
@@ -120,6 +125,21 @@ Please use https://alpha-api.app.net/ to access the APIs.
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-posts-created-by-a-user">Retrieve Posts created by a User</a></td>
</tr>
<tr>
+ <td>/stream/0/posts/[post_id]/star</td>
+ <td>POST</td>
+ <td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#star-a-post">Star a Post</a></td>
+ </tr>
+ <tr>
+ <td>/stream/0/posts/[post_id]/star</td>
+ <td>DELETE</td>
+ <td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#unstar-a-post">Unstar a Post</a></td>
+ </tr>
+ <tr>
+ <td>/stream/0/users/[user_id]/stars</td>
+ <td>GET</td>
+ <td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-posts-starred-by-a-user">Retrieve Posts starred by a User</a></td>
+ </tr>
+ <tr>
<td>/stream/0/users/[user_id]/mentions</td>
<td>GET</td>
<td><a href="/appdotnet/api-spec/blob/master/resources/posts.md#retrieve-posts-mentioning-a-user">Retrieve Posts mentioning a User</a></td>
View
286 resources/posts.md
@@ -157,6 +157,7 @@ You can also create a Post by sending JSON in the HTTP post body that matches th
"reply_to": null,
"thread_id": "1",
"num_replies": 0,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -170,7 +171,8 @@ You can also create a Post by sending JSON in the HTTP post body that matches th
"len": 17
}],
"links": []
- }
+ },
+ "you_starred": false
},
"meta": {
"code": 200,
@@ -201,6 +203,7 @@ You can also create a Post by sending JSON in the HTTP post body that matches th
"reply_to": null,
"thread_id": "1",
"num_replies": 0,
+ "num_stars": 0,
"annotations": [
{
"type": "net.app.core.geo",
@@ -223,7 +226,8 @@ You can also create a Post by sending JSON in the HTTP post body that matches th
"len": 17
}],
"links": []
- }
+ },
+ "you_starred": false
},
"meta": {
"code": 200,
@@ -281,6 +285,7 @@ Returns a specific <a href="/appdotnet/api-spec/blob/master/objects.md#post">Pos
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -299,7 +304,8 @@ Returns a specific <a href="/appdotnet/api-spec/blob/master/objects.md#post">Pos
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false
},
"meta": {
"code": 200,
@@ -360,6 +366,7 @@ Delete a <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post</a>. The
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -378,7 +385,8 @@ Delete a <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post</a>. The
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false
},
"meta": {
"code": 200,
@@ -442,6 +450,7 @@ Retrieve all the <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post<
"reply_to": "1",
"thread_id": "1",
"num_replies": 0,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "mthurman",
@@ -451,7 +460,8 @@ Retrieve all the <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post<
}],
"hashtags": [{],
"links": []
- }
+ },
+ "you_starred": false
},
...
],
@@ -521,6 +531,7 @@ Get the most recent <a href="/appdotnet/api-spec/blob/master/objects.md#post">Po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -539,7 +550,254 @@ Get the most recent <a href="/appdotnet/api-spec/blob/master/objects.md#post">Po
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false
+ },
+ ],
+ "meta": {
+ "code": 200,
+ "max_id": "47",
+ "min_id": "1"
+ "more": true
+ }
+}
+```
+
+## Star a Post
+
+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.
+
+> This endpoint is currently migrated by the ```response_envelope``` migration. Please refer to the [Migrations documentation](/appdotnet/api-spec/blob/master/migrations.md#current-migrations) for more info.
+
+### URL
+> https://api.app.net/stream/0/posts/[post_id]/star
+
+### Data
+
+<table>
+ <thead>
+ <tr>
+ <th>Name</th>
+ <th>Required?</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>post_id</code></td>
+ <td>Required</td>
+ <td>string</td>
+ <td>The post id</td>
+ </tr>
+ </tbody>
+</table>
+
+### Example
+
+> POST https://api.app.net/stream/0/posts/1/star
+```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": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
+ "source": {
+ "name": "Clientastic for iOS",
+ "link": "http://app.net"
+ },
+ "machine_only": false,
+ "reply_to": null,
+ "thread_id": "1",
+ "num_replies": 3,
+ "num_stars": 1,
+ "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_starred": true
+ },
+ "meta": {
+ "code": 200,
+ }
+}
+```
+
+## Unstar a Post
+
+Remove a Star from a Post.
+
+> This endpoint is currently migrated by the ```response_envelope``` migration. Please refer to the [Migrations documentation](/appdotnet/api-spec/blob/master/migrations.md#current-migrations) for more info.
+
+### URL
+> https://api.app.net/stream/0/posts/[post_id]/star
+
+### Data
+
+<table>
+ <thead>
+ <tr>
+ <th>Name</th>
+ <th>Required?</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>post_id</code></td>
+ <td>Required</td>
+ <td>string</td>
+ <td>The post id</td>
+ </tr>
+ </tbody>
+</table>
+
+### Example
+
+> DELETE https://api.app.net/stream/0/posts/1/star
+```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": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
+ "source": {
+ "name": "Clientastic for iOS",
+ "link": "http://app.net"
+ },
+ "machine_only": false,
+ "reply_to": null,
+ "thread_id": "1",
+ "num_replies": 3,
+ "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_starred": false
+ },
+ "meta": {
+ "code": 200,
+ }
+}
+```
+
+## Retrieve Posts starred by a User
+
+Get the most recent <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post</a>s starred by a specific <a href="/appdotnet/api-spec/blob/master/objects.md#user">User</a> in reverse post order. Stars are a way for Users to
+save posts without rebroadcasting the Post to their followers.
+
+> This endpoint is currently migrated by the ```response_envelope``` migration. Please refer to the [Migrations documentation](/appdotnet/api-spec/blob/master/migrations.md#current-migrations) for more info.
+
+### URL
+> https://api.app.net/stream/0/users/[user_id]/stars
+
+### Parameters
+
+<table>
+ <thead>
+ <tr>
+ <th>Name</th>
+ <th>Required?</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>user_id</code></td>
+ <td>Required</td>
+ <td>string</td>
+ <td>The user id. If the user id is <code>me</code> the current authenticated user will be used. You can also specify <code>@username</code> as a <code>user_id</code>.</td>
+ </tr>
+ </tbody>
+</table>
+
+*See [General Parameters](#general-parameters) for optional parameters you can use with this query.*
+
+### Example
+
+> GET https://api.app.net/stream/0/users/1/stars
+```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": "<span itemprop=\"mention\" data-mention-name=\"berg\" data-mention-id=\"2\">@berg</span> FIRST post on <a href=\"https://join.app.net\" rel=\"nofollow\">this new site</a> <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
+ "source": {
+ "name": "Clientastic for iOS",
+ "link": "http://app.net"
+ },
+ "machine_only": false,
+ "reply_to": null,
+ "thread_id": "1",
+ "num_replies": 3,
+ "num_stars": 1,
+ "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_starred": true
},
],
"meta": {
@@ -606,6 +864,7 @@ Get the most recent <a href="/appdotnet/api-spec/blob/master/objects.md#post">Po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -624,7 +883,8 @@ Get the most recent <a href="/appdotnet/api-spec/blob/master/objects.md#post">Po
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false
},
],
"meta": {
@@ -672,6 +932,7 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -690,7 +951,8 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false
},
],
"meta": {
@@ -739,6 +1001,7 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -757,7 +1020,8 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false
},
],
"meta": {
@@ -804,6 +1068,7 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
+ "num_stars": 0,
"entities": {
"mentions": [{
"name": "berg",
@@ -822,7 +1087,8 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"pos": 20,
"len": 13
}]
- }
+ },
+ "you_starred": false
},
],
"meta": {
View
98 resources/users.md
@@ -780,3 +780,101 @@ None.
}
}
```
+
+## List Users who have starred a Post
+
+List all the Users who have starred a given Post.
+
+> This endpoint is currently migrated by the ```response_envelope``` migration. Please refer to the [Migrations documentation](/appdotnet/api-spec/blob/master/migrations.md#current-migrations) for more info.
+
+### URL
+> https://api.app.net/stream/0/posts/[post_id]/stars
+
+### Parameters
+
+<table>
+ <thead>
+ <tr>
+ <th>Name</th>
+ <th>Required?</th>
+ <th>Type</th>
+ <th>Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td><code>post_id</code></td>
+ <td>Required</td>
+ <td>string</td>
+ <td>The post id</td>
+ </tr>
+ </tbody>
+</table>
+
+### Example
+
+> GET https://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 <a href=\"https://github.com/appdotnet/api_spec\" rel=\"nofollow\">teaching you</a> about the <span itemprop=\"mention\" data-mention-name=\"appdotnet\" data-mention-id=\"3\">@appdotnet</span> Stream #<span itemprop=\"hashtag\" data-hashtag-name=\"api\">API</span>.",
+ "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"
+ },
+ "cover_image": {
+ "height": 118,
+ "width": 320,
+ "url": "https://example.com/cover_image.jpg"
+ },
+ "type": "human",
+ "created_at": "2012-07-16T17:23:34Z",
+ "counts": {
+ "following": 100,
+ "followers": 200,
+ "posts": 24
+ },
+ "app_data": {
+ "appdotnet": {...},
+ "rdio": {...}
+ },
+ "follows_you": false,
+ "you_follow": true,
+ "you_muted": true,
+ },
+ ...
+ ],
+ "meta": {
+ "code": 200
+ }
+}
+```

1 comment on commit 0fc3d2c

@kosso

Would it be useful to have a total count of posts starred by the user in User.counts ?

Please sign in to comment.
Something went wrong with that request. Please try again.