Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Tree: 29d7545a11
Fetching contributors…

Cannot retrieve contributors at this time

623 lines (579 sloc) 21.954 kB

Objects

User

A user is the central object utilized by the App.net Stream API. They have usernames, follow other users, and post content for their followers.

Example User object

{
    "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,
        "stars": 76
    },
    "app_data": {
        "appdotnet": {...},
        "rdio": {...}
    },
    "follows_you": false,
    "you_follow": true,
    "you_muted": false,
}

User fields

Field Type Description
id string Primary identifier for a user. This will be an integer, but it is always expressed as a string to avoid limitations with the way JavaScript integers are expressed. This idspace is unique to User objects. There can be a Post and User with the same ID; no relation is implied.
username string Case insensitive. 20 characters, may only contain a-z, 0-9 and underscore.
name string User supplied descriptive name. May be a pseudonym. All Unicode characters allowed. Maximum length N characters.
description object
Field Type Description
text string User supplied biographical information. All Unicode characters allowed. Maximum length N characters.
html string Server-generated annotated HTML version of biographical information.
entities object Entities included in biographical information. See information on entities for reference.
timezone string User timezone in tzinfo format.
locale string User locale in ISO format.
avatar_image image object Object representing the URL and original size of the user's avatar.
cover_image image object Object representing the URL and original size of the user's over image.
type string An account can be one of the following types: human, bot, corporate, or feed.
created_at string The time at which the User was created in ISO 8601 format.
counts object
Field Type Description
following integer The number of users this user is following.
followers integer The number of users following this user.
posts integer The number of posts created by this user.
stars integer The number of posts starred by this user.
app_data object Object where each app can store opaque information for this user. This could be useful for storing application state (read pointers, default filters in the app, etc).
follows_you boolean Does this user follow the user making the request? May be omitted if this is not an authenticated request.
you_follow boolean Does the user making the request follow this user? May be omitted if this is not an authenticated request.
you_muted boolean Has the user making the request blocked this user? May be omitted if this is not an authenticated request.

Deprecations

  • is_following, is_follower, and is_muted have all been deprecated and replaced with follows_you, you_follow, and you_muted. These keys should not be used and will be removed from the User object soon.

Images

Images are objects so that app developers can more easily pick the appropriated sized image for different contexts.

{
    "height": 512,
    "width": 512,
    "url": "https://example.com/image.jpg"
}

Images may be dynamically resized on the server by adding w and/or h parameters to the query string of the URL as desired. If one of the parameters is omitted, the omitted dimension will be scaled according to the aspect ratio of the original image. Images 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.

Post

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.

{
    "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_reposts": 1,
    "num_stars": 1,
    "annotations": [
        {
            "type": "net.app.core.geo",
            "value": {
                "type": "Point",
                "coordinates": [102.0, .5]
            }
        }
    ],
    "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": true,
    "you_starred": false,
    "reposters": [
        ...user...
    ],
    "starred_by": [
        ...users...
    ]
}

Post Fields

Field Type Description
id string Primary identifier for a post. 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. Note: In certain cases (e.g., when a user account has been deleted), this key may be omitted.
created_at string The time at which the post was create in ISO 8601 format.
text string User supplied text of the post.
html string Server-generated annotated HTML rendering of post text.
source object
Field Type Description
name string Description of the API consumer that created this post.
link string Link provided by the API consumer that created this post.
reply_to string The id of the post this post is replying to (or null if not a reply).
thread_id string The id of the post at the root of the thread that this post is a part of. If thread_id==id than this property does not guarantee that the thread has > 1 post. Please see num_replies.
num_replies integer The number of posts created in reply to this post.
num_stars integer The number of users who have starred this post.
num_reposts integer The number of users who have reposted this post.
annotations list Metadata about the entire post. See the annotations documentation.
entities object Rich text information for this post. See the entities documentation.
is_deleted boolean Has this post been deleted? For non-deleted posts, this key may be omitted instead of being false. If a post has been deleted, the text, html, and entities properties will be empty and may be omitted.
machine_only boolean Is this Post meant for humans or other apps? See Machine only Posts for more information.
you_starred boolean Have you starred this Post? May be omitted if this is not an authenticated request.
starred_by list A partial list of users who have starred this post. This is not comprehensive and is meant to be a sample of users who have starred this post giving preference to users the current user follows. This is only included if include_starred_by=1 is passed to App.net. May be omitted if this is not an authenticated request.
you_reposted boolean Have you reposted this Post? May be omitted if this is not an authenticated request.
reposters list A partial list of users who have reposted this post. This is not comprehensive and is meant to be a sample of users who have starred this post giving preference to users the current user follows. This is only included if include_reposters=1 is passed to App.net. May be omitted if this is not an authenticated request.
repost_of Post object If this post is a repost, this key will contain the complete original Post.

Deprecations

  • 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 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 in Alpha's Global Feed?"

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.

Entities are designed to be very simple to render — they should relatively easily translate into NSAttributedString objects and the like.

Ranges specified by entities may be adjacent, but may not overlap.

All of the following examples are about the following post:

@berg FIRST post on this new site #newsocialnetwork

Mentions

Bring another user's attention to your post. A mention starts with @.

"mentions": [{
    "name": "berg",
    "id": "2",
    "pos": 0,
    "len": 5,
}]
Field Type Description
name string The username being mentioned (doesn't include '@').
id string The user id of the mentioned user.
pos integer The 0 based index where this entity begins text (include @).
len integer The length of the substring in text that represents this mention. Since @ is included, len will be the length of the name + 1.

Hashtags

Tag a post about a specific subject. A hashtag starts with #.

"hashtags": [{
    "name": "newsocialnetwork",
    "pos": 34,
    "len": 17
}]
Field Type Description
name string The text of the hashtag (not including #).
pos integer The 0 based index where this entity begins text (include #).
len integer The length of the substring in text that represents this hashtag. Since # is included, len will be the length of the name + 1.

Links

Link to another website.

"links": [{
    "text": "this new site",
    "url": "https://join.app.net"
    "pos": 20,
    "len": 13
}]
Field Type Description
text string The anchor text to be linked (could be a url).
url string The destination url (only http or https accepted).
pos integer The 0 based index where this entity begins text.
len integer The length of the substring in text that represents this link.

Filter

A Filter functions as either a whitelist or a blacklist over a stream of Posts. All the predicates are logically OR'ed together. For instance, with the following example, a post will be shown if it's from user 1, or it's from user 2, or it has hashtag 'sf', or it links to app.net, or it mentions user 1.

{
    "id": "1",
    "type": "show",
    "name": "On the go",
    "user_ids": ["1", "2"],
    "hashtags": ["sf"],
    "link_domains": ["app.net"],
    "mention_user_ids": ["1"]
}
Field Type Description
type string Either show or block for whether this filter should exclude everything except for what's shown or show everything except for what's blocked.
name string A User assigned name for this filter.
user_ids list A list of user ids a Post must or must not be created by.
hashtags list A list of hashtags a Post must or must not have.
link_domains list A list of domains a Post must or must not have a link to.
mention_user_ids list A list of user ids a Post must or must not mention.

Notes on data formats

Dates

Dates will be formatted as a strict subset of ISO 8601. Dates are parseable by almost any ISO 8601 date parser or merely by parsing from position. All dates will be formatted as follows:

2012-12-31T13:22:55Z

where 2012 is the year, 12 represents December, 31 represents the 31st day of the month, 13 represents 1 PM, 22 minutes and 55 seconds past the hour. All times will be expressed in terms of UTC.

This format was chosen to minimize ambiguity and edge cases in terms of parsing while maximizing readability of dates during development.

Object IDs

Object ids will always be transferred as strings to avoid issues with with limitations of JavaScript integers. You can assume that object ids are integers.

Jump to Line
Something went wrong with that request. Please try again.