App.net API Documentation is on the web at https://developers.app.net. Source for these docs is in the new-docs branch here. Please use the issue tracker and submit pull requests! Help us build the real-time social service where users and developers come first, not advertisers.
Home Page: https://developers.app.net
Some objects returned by current API have a property named indices, i.e. Mentions. However, the format of this property is not as readable as it could be if we used an idea of range.
For example, an equivalent to "indices": [34, 42] would be "range": [34, 8]. I believe this is a better way to recognize a substring within a piece of text. Makes sense?
https://github.com/appdotnet/api-spec/blob/master/objects.md#links
Something like a subset of the total URL (e.g. remove http(s):// and limit length). This is the version that should be used in the pre-processed text_html mentioned in #8
Looking over the API doc, could images be generalized as a media type which are then subcategorized based on MIME types? this would leave the door open for videos as well. If annotations could be attached to the media type, then we could create a pretty versatile bucket for dumping metadata (like EXIF). This could keep the core objects pretty small.
Just as there's an "Image object" type, there should be a "Text object" type that contains text, HTML, and entities. This is how a User's description works now; it could also be used to give a Post object a content field instead of putting text, HTML, and entities fields directly on it.
That makes the whole thing more orthogonal: The "Text object" type can be defined in one place in the spec no matter where it's used (and it can be used in more places in later versions), and apps built on the spec can implement a single Text object parser and internal representation.
When I download my stream from the API to my iOS client on one post all the post values are null:
{
annotations = {
};
"created_at" = "2012-08-11T06:44:59Z";
deleted = 1;
entities = {
hashtags = (
);
links = (
);
mentions = (
);
};
html = "";
id = 21115;
"reply_to" = 21101;
source = {
link = "";
name = "";
};
text = "";
user = {
"app_data" = "";
"avatar_image" = {
height = 200;
url = "https://d1f0fplrc06slp.cloudfront.net/assets/user/0a/e0/00/0ae0000000000000.jpg";
width = 200;
};
counts = {
"followed_by" = 0;
follows = 0;
posts = 0;
};
"cover_image" = {
height = 1707;
url = "https://d1f0fplrc06slp.cloudfront.net/assets/user/79/e0/00/79e0000000000000.jpg";
width = 1280;
};
"created_at" = "2012-08-10T01:08:16Z";
description = {
entities = {
hashtags = (
);
links = (
);
mentions = (
);
};
html = "<span itemscope="https://app.net/schemas/Post\">I am a network researcher working on ProtoGENI and Emulab. In my spare time I sometimes make flash games like "Tile Factory" and "Shattered Colony: The Survivors". I am interested in making an actual social game (as opposed to nagware like Zynga).";
text = "I am a network researcher working on ProtoGENI and Emulab. In my spare time I sometimes make flash games like "Tile Factory" and "Shattered Colony: The Survivors". I am interested in making an actual social game (as opposed to nagware like Zynga).";
};
id = 1268;
locale = "en_US";
name = "Jonathon Duerig";
timezone = "America/Los_Angeles";
type = human;
username = duerig;
};
}
This is only happening for this one post.
Besides the specific fields you decide to place into Counts for core object(s), consider making annotations (namespace by user name ) to Counts with as permission = "readonly" for apps outside the namespace, but of course "updateable" for the username that "owns" the count.
Idea being as a app developer, I can create a count that I want other apps to see but not update (by annotating the Counts of the core object) or I can chose to keep that count private to my app if I use an annotation on the core object itself.
Am I interpreting correctly that developer annotations on core objects will be private to the developer's app (i.e. not seen by other apps outside the namespace)? If not, that's another issue. public and private annotations. :-)
Everyone knows that Twitter launched on SMS with its 160 character limit, which they embraced to restrict content to 140 characters. It also meant that all metadata must be sent inbound with the message data which I think has been a restriction.
Would it be possible to send metadata separately from the message? So, they would be listed in the post's entities, and not contributing to the 140 (or other) character limit? The obvious types of metadata would be URLs, and trailing hashtags (tags not in the message body, but appended to the message at the end).
So, it looks like you've done half of this in your Post object example, the trailing hashtag is listed as an entity, but it's still in the message.
The benefits of this would be that clients can be much more flexible about how metadata is displayed. User's get the full 140 characters for their message content. It would allow for much greater flexibility in how Posts are used - it would be possible to tweet a whole photo album for example.
I am on the alpha, and I can successfully create an app, authenticate a user to get a user access token and and access the user stream API. However, the public stream request returns 404 (https://alpha-api.app.net/stream/0/streams/public) Does then mean the public stream API is not available yet?
Or do I need a client access token to access this? If so, what endpoint do pass my client_id/client_secret to? I tried to POST to the public stream resource with my client_id/client_secret with no success.
Not sure where the best place to post this question is. Feel free to redirect me. Thanks! Looking forward to building some apps!
The precision of the creation date timestamp for posts is currently one second. Posts on the global feed will soon start coming in at several (many) per second. Having timestamps that include fractions of a second will soon be important for clients that need to re-sort posts by creation time.
To save devs the effort of having to write a text/entity processor for every framework, should just include a pre-processed one that is in HTML
for eg: when I click @berg I want to get the user profile for that user.
While I'm not trying to open up the can of worms that is the permissions model discussion, I do think it would make sense to have some rudimentary idea of posts that are public, vs posts that are private or limited in viewing scope. I would add something like the following to the Post object:
For public posts:
"viewable": "all",
For private/limited posts:
"viewable": "@berg, @DreadPirateRyan, @daltonc",
Allow App dot Net to import information, mainly contact information and images, from other social platforms. I believe a big concern for others, especially those who use social media on a daily basis, will be concerned of all the lost data from switching platforms.
appnet users: randyg
I anticipate this system will have a heavy usage on photos.
That being said, we've done a bit of work on this front. We should at least reuse or learn from the photo object we've come up with.
https://github.com/photo/frontend/blob/master/documentation/schemas/Photo.markdown
Happy to discuss why these fields are included.
If you're building a network for apps to build on top of, why restrict interaction to text and url interchange?
One possible generalisation would be to support developer defined protocols (public and private), e.g.:
"created_at": "2012-07-16T17:25:47Z",
"protocol": "text"
"content": "@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"
},
Here "html" becomes an optional field that will be included for protocols that it makes sense to render directly - maybe only text, unless there's some plugin for developers to tell you how render their protocol content as HTML.
Then developers can invent M2M protocols and build all kinds of things on top of feeds that involve interactions between users - encrypted conversations, social games, virtual currency/goods exchange, some future replacement for emoticons, voting systems, etc.
Clients simply use filters to get the protocols they understand and ignore everything else.
Of course you could do most of these things in plain text posts with urls but then you'd be putting some messy stuff into users visible feeds for the clients that don't understand them. Looking at the spec I thought you could bend application defined annotations in this direction but that also seems like an abuse of the terminology, not very self-documenting in terms of what client developers should do and makes it hard to create open protocols that multiple apps support.
If you do add protocols it might also make sense to add a list of supported protocols to the user object, so client apps can decide whether to just start speaking a certain protocol to someone or send them an invite url to a new app.
Are emails unique across users?
In this post http://daltoncaldwell.com/3rd-party-rev-share Dalton proposes some type of revenue sharing where application developers are given a cut of app.net's user fees base on some concept of how much those apps are "used." This is what I would call platform -> app revenue sharing. I suggest that it would be better to share revenue the other way around - app -> platform.
Dalton clearly notes that it is very hard to come up with a the right concept of "usage." Should it be time, number of posts, etc.? All of these are very imperfect indicators of how much value an app gives to it's users. Is a site that gets me from point A to point B very quickly more valuable, or a site that keeps me hanging around for a long time more valuable? Google was the former, and Yahoo! the latter. However, it wasn't clear that a quick search engine was more valuable than a portal site until users voted with their feet and clicks, and advertisers voted with their money.
Any proxy for value like time, posts, etc. will likely fail to serve a large set of developers, and over-reward another set. It also artificially caps the amount a user can pay to developers at some fraction of the annual subscription rate, when many users might actually gain (and being willing to pay) much more value.
To this end, I think Apple's app model gets one piece largely right. App developers make applications that are valuable to users. Users clearly express how valuable the application is by paying the developer. Because the platform is valuable to the developer, and allowed them to create the product in the first place, the developer gives the platform a cut of their revenue.
This won't solve a lot of problems. App.net will still have to decide what to do about app developers who want to sell users to advertisers in the exact way that App.net has shunned. However, this issue occurs in any app system, regardless of how it implements revenue sharing, or whether it implements it all.
It is also worth noting that as app.net became more inviting to app developers, and app profits increased, the base subscription rate could be lowered, and yet users would still be essentially paying for the platform.
I believe this model would cleanly and efficiently help app developers make valuable tools, and would integrate well with App.net's vision for having a highly federated platform.
Being able to set the exact date and time of a post, before it is sent would would rock. By making them transparent (i.e. a 'future posts' menu option so you could see who has what pending) you could really turn the network into something else.
With transparency, you could highlight any marketing spam, and we could have a platform that is both realtime and constantly looking at the future...
Hi all,
I love the App.net project and wanted to contribute in some way. I've just created a sample PHP library with wrapper functions for the unreleased stream API. It is not implementing any sort of OAuth/security measures yet.
You can find it here: https://github.com/jdolitsky/AppDotNetPHP
Please use this to inspire your own developer libraries, or help me maintain this one!
Thanks!
Josh Dolitsky
Given that you're using JavaScript Object Notation, shouldn't you be using JavaScript naming conventions? They're easy enough to convert in most server-side languages to something that's more idiomatic to the backend processing language, if that's necessary, but it's a particularly obnoxious step to have to take in any kind of client-side code.
Would be nice to have (fine-grained) permissions for app_data (default from the app developer, modifiable by the user).
For the Rdio example mentioned in the specs, assume that more than just the song id is annotated by the Rdio app. Embedding the rdio song id publicly makes sense. But, you might not want the world to know that the song was on your "gettin groovy" playlist, so you'd make that component private.
Another example would be some type of weight loss app. You could share your percentage progress publicly, but for better accountability, you'd share the actual gain/loss in lbs with your support group.
I could easily seen this implemented as a dictionary of app_data keys mapping to groups/user id lists.
Posts should be able to be restricted in their visibility at the API. This means a Post is never delivered through the API to a Stream which is not allowed to see it. The inclusion of access control would have a profound impact on the platform and would enable a huge variety of apps and use cases that are not possible under existing social networks and message routing systems.
This will enable lots of use cases that could really blow up the utility of the service beyond a Twitter-style system. Some examples include:
I have a client token that is authenticated with stream only. When I view my profile the counts are all zero and they are non zero on alpha.app.net (as they should be). user @josh.
URL
https://alpha-api.app.net/stream/0/users/me?access_token=...
Results
{
"app_data": null,
"avatar_image": {
"height": "200",
"url": "https://d1f0fplrc06slp.cloudfront.net/assets/user/5d/50/00/5d50000000000000.jpg",
"width": "200"
},
"counts": {
"followed_by": "0",
"follows": "0",
"posts": "0"
},
"cover_image": {
"height": "230",
"url": "https://d1f0fplrc06slp.cloudfront.net/assets/user/fe/50/00/fe50000000000000.jpg",
"width": "960"
},
"created_at": "2012-08-08T01:09:05Z",
"description": {
"entities": {
"hashtags": [],
"links": [],
"mentions": []
},
"html": "<span itemscope="https://app.net/schemas/Post\">Levity is the cosmological constant.",
"text": "Levity is the cosmological constant."
},
"id": "390",
"locale": "en_US",
"name": "Josh schlesser",
"timezone": "America/Los_Angeles",
"type": "human",
"username": "josh"
}
For the image object, it would be nice to allow small images to just send back their base64 encoding, as opposed to the URL. Something like this:
"16s": {
"height": 16,
"width": 16,
"base64": "iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAABmJLR0QA/wD/AP+gvaeTAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAB3RJTUUH1woICQIzztyOYgAAAHVJREFUeNpj/P//f3t7OwNuICwsnJaWBueyQKjExABcGjZtOhwWFrZq1SoUDRISmrjtOLxq1Sq4HiYGIkBYWBicZCGoOi0tzcjIiIGBoauriygNDAwMJiYmcDZRTkIGoxpoogEacWfPniVBw/nz58+fP0+kBgCxLR/Dk4eUOQAAAABJRU5ErkJggg=="
},
In a project I worked on a while back, we had to fetch tons of small images from urls. We instead started sending down the base64 encoding instead of the url, which saved us a round-trip in fetching the image. For a small image like this (16 x 16), the extra bandwidth to send the encoded text is negligible compared to the cost of opening another http request and pulling down the image.
I think applying the http://activitystrea.ms schema is essential for app.net.
The ability to tag posts by language lets you discard posts in languages you don't understand, and post in your non-English language without pestering foreign followers. I guess this requires a language field in the post object.
When Twitter launched annotations, I really digged the idea.
What are the expected limitations of this? Will there a be limit on how much annotations a post will have?
Considering that this will create a new set of keywords that developers might have to decide on, will app.net help in establishing standards? Or should developers establish standards themselves? In other words, say I want to add an annotation of a song, I might use something like "song", as opposed to my own site's tag "tweeklyfm:song" for standard's sake. Perhaps another way around this, is allow "vendor" annotations, but then also allow the addition of a "tag" field in the annotation. ie, with the rdio example:
"annotations": {
"rdio:song": {
"tag":"music",
...
}
}
I think one of the great benefits of annotations will be the extraction of metadata from posts. ie, you can fetch all the songs with music information in it. Or all the posts with news annotations? It would be great if there is an endpoint that allows developers to retrieve posts by searching annotations. It seems you don't have a search endpoint yet, but it can be included in that by specifying it in the query parameters?
First off, I want to confirm one thing: the auth spec appears to imply that an app that only uses the client-side flow never needs to use the client_secret at all (as does the OAuth i-d). Is this correct?
Anyway, the client-side flow requires directing the user to a URL on App.net, having them log in, and getting back a token via an HTTP redirect. I'm guessing the imagined use case is an HTML5 app, an iOS app, etc., where there's a convenient web browser available, and where there's an obvious URL to receive the token callback on a redirect (the actual URL of the HTML5 app, a custom protocol scheme registered with iOS, etc.).
This is pretty awkward for a command-line client, since there may be no web browser, and even if there is a web browser, there may be no way to receive the redirect back in the app. I'm curious if you've considered this use case, and have a recommendation. (I specifically want to add support to Barnowl, which is a multi-protocol client that you can basically treat like your favorite command-line IRC client for the purposes of this discussion.)
One option would be to allow an explicit way for an API client to pass a username and password. I can see why this would be distasteful, but note that disallowing it is only mild obfuscation -- it's pretty possible for me to scrape your login page and write code to take a username and password, hit the login page, programatically authorize my app, and return back to it.
Another option would be to generate an app-specific password on the web interface (think Google's fallback for using protocols like IMAP or XMPP when you have 2-factor authentication). This would be simple enough for the user to do, and simple enough to support on the application end. For bonus elegance points, the app-specific password should just be an access token, although a password usable with e.g. SSL-protected Basic auth would be fine too.
I also note that the spec does not specify when an access token will expire, or whether they expire at all. For a long-running command-line client on a remote machine in a screen session, we'll preferably want the access token to be usable indefinitely, and if not we'll want an explicit expiration time so we can alert the user enough in advance to re-do the auth flow while they're connected (preferably a day or so in advance, so tokens should last at least several days if requested). Can this be clarified?
One advantage of the app-specific password approach is it makes it abundantly clear how long that password is valid, namely, as long as that app-specific password is still listed on the user's profile, and it also makes it obvious how to revoke access for a client.
A related use case that's worth considering is robot accounts (commit notifications, etc.), where some code legitimately has a password of its own, and ideally a human doesn't need to visit a website even if the bot needs to be restarted.
No need to say, it is key to have a Oauth authentication scheme. http://oauth.net
One of the most annoying parts of mobile apps for sharing services is the often-awkward "refresh delay" before new content is displayed. In the case of most twitter apps, the developers of said apps have abrogated the decision of when to refresh quickly to the user. API vendors have encouraged this behavior because stream connections are relatively expensive (for a power-constrained client and the servers).
But a better API would give us a very inexpensive (for both client and server) way to ask, "Is there new activity I should be interested in?" and also give an idea of the frequency of said updates for adaptive frequency checks. Backgrounded mobile apps may stick to long polls (for power efficiency) and desktop services may just use a streaming api, but foregrounded mobile apps are left out in the cold in this approach.
An easy way to do this would be to support both Etags and HEAD method requests on the posts API, which currently seems to be omitted from the spec. Lightweight apps could use this to avoid excessive network traffic while still keeping a sub-5-second response time on new content to the user.
Hi,
I'd like to know if you considered using EventSource for streams and, if yes, why you didn't take it.
When sending a user to the OAuth page I get "OAuth error. Sorry :(" I have tried replacing my Client ID with AppApp's client ID since that is public and it works fine. This seems to be only with my Client ID and then I created a new App on the App.net website and used that Client ID and that still didn't work.
Hi. Are there any plans to make post deletion events available via subscription?
From my experience it's not worth calling something REST, RESTful, REST-inspired, RESTlike or anything of the sort unless you want endless debates about the RESTfulness of your API. I think that would be a distraction to the cause.
Unless you're planning to fully embrace all of the REST constraints (hypermedia, versioned content types, etc) I would avoid it.
I propose: HTTP API or JSON API.
Please can we consider adding a field to the Filter object - allowing a filter to show or block based on post.text containing filter.text (ditto post.html containing filter.html).
For bonus karma can filter.text or filter.html please allow match by regex? (a nice to have, plain text match would do)
As an app.net member, I never want to see a post that contains text "4sq.com" OR "became mayor of" ever again.
This is probably one for further down the line, but worth getting the request in early…
I recently wrote a Twitter service called Who Will See It? (http://whowillseeit.com/), which shows whose Twitter streams an @-reply tweet will appear in. Basically, it de-dupes the Twitter follow list of the tweet poster and the first tweet recipient. It's useful for checking whether a tweet you post will appear in lots of people's streams, which can be handy to sense-check whether it's wise to post a reply or not. (It can help you to avoid being noisy on Twitter, or to avoid posting a more personal reply if it'll be seen by lots of people.)
To get this to work, I have to first retrieve the followers list of both the poster and the recipient. Twitter splits the "user's followers" API call into pages of up to 5,000 users at a time, to keep the returned JSON to a reasonable size. As a result, Who Will See It? currently only works for people with 5,000 followers or fewer. (I'll implement paging at some point, but for now it's just the first 5,000.)
Having de-duped the lists, I then retrieve user details for the matching users, so I can show a list of who will see the tweet. Twitter's user retrieval API only allows the retrieval of up to 100 users at a time, so again, this functionality is limited at present until I implement paging.
What I'd ideally like is a way to retrieve the list of overlapping followers in a single query, thereby saving a ton of de-duping. If this returned the details for the overlapping users, then all the better. Twitter doesn't have this at present.
Once app.net takes off, I'd love to adapt Who Will See It? to work here too. So, an API call to retrieve the overlapping followers for a pair of usernames would be really helpful. (It could also be useful for network visualisation purposes.) Good luck with api.net, and fingers crossed you make the funding!
The Post object includes an html property which, in this example, includes classes. Since the className could potentially conflict with the client's own css, I would recommend replacing it with microdata. So the example becomes:
<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>.Response for 'stream/0/posts' always returns 198 entries when count param is specified.. returns 20 entries when count is omitted though.
This feels a little off-topic for the API spec but Dalton's blog on revenue sharing linked here, so...
Assuming the hosting economics work, consider:
Deleted posts can't count and there should be some feature to enable spam reporting so offending apps get kicked out. You might also want to weight posts by visibility (i.e. more for public posts and less for private ones, possibly even on a scale for how many people they are addressing).
If you go with my other suggestion (#20) then you may also consider applying a log scale to the totals for each app before you compare them - so that games don't dominate and the revenue shares are more even across multiple clients used for different purposes.
A bonus for a post-only approach is that it will probably make sense for existing popular apps and websites to integrate another sharing option, even if the user-base is relatively small.
api - /stream/0/posts
When clients request for posts since min_id, the response contains the post with min_id. Clients now have to specifically remove this post from the response before displaying the response. To avoid this, if the min_id is passed as last_returned_id+1, the response for some reason includes the entire list of posts. Is this a bug ?
IMO, I would prefer that the response did not include the post with min_id.
Potentially a premature optimization, but it's something that's tricky to unwind later. What are your thoughts on making object IDs something like a timeuuid? It makes running in a distributed fashion easier, and potentially #22 too. I notice the datatype for objects ID is already described as an alphanumeric strring, but all example show it as a quoted integer. Might just be a case of clarifying the docs.
@daltonc vision is spot on when he writes " I believe that a number of smaller, interoperable social platforms with a clear, sustainable business models will usurp you. " However I don't see anything in the current API ideas that leads to an open, federated, ecosystem of smaller players.
Thanks to federation, users can decide in which silo they want to lock their data (their own if they prefer), and smaller players (like niche/local social networks) can join the ecosystem, growing the network of users. This does not mean that app.net has to be open source. It can remains a closed source service with a business model behind it.
However, interoperability is not something you build on 'top' but has to be thought in the core. Now is the right time to think about these concepts. Having a look at existing projects (statusnet, diaspora, onesocialweb, friendika,...) and specifications (Ostatus, Activitystreams, Webfinger, Salmon, ...) would help.
A good starting point is to reach out to the W3C Federated Social Web community: http://www.w3.org/community/fedsocweb/
I think a concept of API middleware would be extremely awesome for App.net. I've written up a doc on it here: https://github.com/railsjedi/api-spec/blob/master/middleware.md
This would allow apps to handle status posts and receive HTTP callbacks to provide before/after actions on them.
It's a rough spec, still needs work but would be very interested in this functionality if it's possible.
Currently you can only get the avatar sizes of 183px?
Would it be possible to add smaller image dimensions to the feed?
Also, allow username to be passed in as the input parameters.
Don't know whether issues are also used for suggestions/ideas but hope so.
One issue that App.net might face is that a paid service might make it difficult to get complete peer groups over, which obviously is a great part of any new social service. I'd love to see the idea of allowing sponsored/paid/bundled memberships.
A good example is Evernote, where a company can decide to sponsor its employees premium accounts, or what Dropbox did with the team edition.
Now, if we would make sponsoring memberships part of the API, that would open up so many opportunities, including e.g. selling an app/client via one of the many App Stores that comes with e.g. a one year membership.
What do you think?
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.