Permalink
Browse files

Annotations are only included if you ask for them. Add a create example.

  • Loading branch information...
1 parent 8eedee1 commit 87dba1a9f14b068c46075305bf4f8e25ff7f5772 @mthurman mthurman committed Sep 1, 2012
Showing with 62 additions and 61 deletions.
  1. +1 −1 annotations.md
  2. +9 −6 objects.md
  3. +52 −54 resources/posts.md
View
2 annotations.md
@@ -92,7 +92,7 @@ Annotations are currently live on in the API. To create them you must give App.n
Every client can choose if/how it chooses to display annotations. As stated above 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. 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. Any annotation in this namespace must be validated by the API against a published schema. Outside of this namespace, developers may create annotations in either the ```net.app.[username]``` namespace or a reversed-domain namespace of their choosing.
-Since annotations can be up to 8192 bytes, they are not included with posts be default. When you make a request for posts, you can include the parameter ```include_annotations=1``` to receive the annotations object. See [general Post parameters](https://github.com/appdotnet/api-spec/blob/master/resources/posts.md#general-parameters) for more information.
+Since annotations can be up to 8192 bytes, they are not included with posts by default. When you make a request for posts, you can include the parameter ```include_annotations=1``` to receive the annotations object. See [general Post parameters](https://github.com/appdotnet/api-spec/blob/master/resources/posts.md#general-parameters) for more information.
# Annotations formats #
View
15 objects.md
@@ -236,12 +236,15 @@ 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,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
+ "annotations": [
+ {
+ "type": "net.app.core.geo",
+ "value": {
+ "type": "Point",
+ "coordinates": [102.0, .5]
+ }
}
- },
+ ],
"entities": {
"mentions": [{
"name": "berg",
@@ -359,7 +362,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 spec](github.com/appdotnet/api-spec/blob/master/annotations.md) for more information
+Post annotations are immutable attributes that describe the entire post. Please see the [Annotations spec](github.com/appdotnet/api-spec/blob/master/annotations.md) for more information.
## Entities
Entities allow users and applications to provide rich text formatting for posts. They provide common formatting for mentions and hashtags but they also allow links to be embedded with anchor text which gives more context. Each entity type is a list with 0 or more entities of the same type.
View
106 resources/posts.md
@@ -90,7 +90,7 @@ Post id is the ordering field for multiple posts (not ```created_at```). ```crea
## Create a Post
Create a new <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post</a> 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 <a href="/appdotnet/api-spec/blob/master/objects.md#post">post schema</a> with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```text```, ```reply_to```, and ```annotations```. To create complex posts, you must use the JSON interface.
+You can also create a Post by sending JSON in the HTTP post body that matches the <a href="/appdotnet/api-spec/blob/master/objects.md#post">post schema</a> with an HTTP header of ```Content-Type: application/json```. Currently, the only keys we use from your JSON will be ```text```, ```reply_to```, and ```annotations```. To create complex posts, you must use the JSON interface. See the [JSON example](#json-example) below.
> 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.
@@ -150,12 +150,58 @@ 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,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
+ "entities": {
+ "mentions": [{
+ "name": "berg",
+ "id": "2",
+ "pos": 0,
+ "len": 5
+ }],
+ "hashtags": [{
+ "name": "newsocialnetwork",
+ "pos": 34,
+ "len": 17
+ }],
+ "links": []
+ }
+ },
+ "meta": {
+ "code": 200,
+ }
+}
+```
+
+### JSON Example
+
+> POST https://alpha-api.app.net/stream/0/posts?include_annotations=1
+> Content-Type: application/json
+> DATA '{"text": "@berg FIRST post on this new site #newsocialnetwork", "annotations": [{"type": "net.app.core.geo", "value": {"type": "Point", "coordinates": [102.0, 0.5]}}]}'
+```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 this new site <span itemprop=\"hashtag\" data-hashtag-name=\"newsocialnetwork\">#newsocialnetwork</span>.",
+ "source": {
+ "name": "Clientastic for iOS",
+ "link": "http://app.net"
},
+ "reply_to": null,
+ "thread_id": "1",
+ "num_replies": 0,
+ "annotations": [
+ {
+ "type": "net.app.core.geo",
+ "value": {
+ "type": "Point",
+ "coordinates": [102.0, .5]
+ }
+ }
+ ],
"entities": {
"mentions": [{
"name": "berg",
@@ -226,12 +272,6 @@ Returns a specific <a href="/appdotnet/api-spec/blob/master/objects.md#post">Pos
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "berg",
@@ -310,12 +350,6 @@ Delete a <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post</a>. The
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "berg",
@@ -397,12 +431,6 @@ Retrieve all the <a href="/appdotnet/api-spec/blob/master/objects.md#post">Post<
"reply_to": "1",
"thread_id": "1",
"num_replies": 0,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "mthurman",
@@ -481,12 +509,6 @@ Get the most recent <a href="/appdotnet/api-spec/blob/master/objects.md#post">Po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "berg",
@@ -571,12 +593,6 @@ Get the most recent <a href="/appdotnet/api-spec/blob/master/objects.md#post">Po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "berg",
@@ -642,12 +658,6 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "berg",
@@ -714,12 +724,6 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "berg",
@@ -784,12 +788,6 @@ Return the 20 most recent <a href="/appdotnet/api-spec/blob/master/objects.md#po
"reply_to": null,
"thread_id": "1",
"num_replies": 3,
- "annotations": {
- "wellknown:geo": {
- "type": "Point",
- "coordinates": [102.0, .5]
- }
- },
"entities": {
"mentions": [{
"name": "berg",

0 comments on commit 87dba1a

Please sign in to comment.