Consider supporting post content other than "text"

[markwilcox]

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.

[ricardobeat]

Isn't it bad to throw HTML around? This encourages API consumers to trust that the data is completely safe without filtering. One bad proxy can ruin it - this could become a vulnerable point for XSS attacks.

[markwilcox]

That's a good point but the "html" field is not part of my suggestion, it's already in the spec.

I'm not sure if the protocol field is really needed - if you've got to filter out protocols then we might as well just use some common hashtag and have it as a convention to filter that if you only want human readable stuff. I quite like the idea of using #! e.g.
#! /games/chess E-2 E-4

[CocoaPriest]

The keyword here is "Metadata". I think, it's a must-have feature – it would be reaaaaaly cool if we could ember some sort of meta-data objects and make it indexable.

[markwilcox]

Metadata is a very broad thing. What sorts of use cases do you want metadata for and could they be covered by:
https://github.com/appdotnet/api-spec/blob/master/objects.md#annotations (which are not yet really defined).

What sort of indexing do you want, currently no filters are defined for annotations either, but that would be a natural progression. Might be worth creating a new issue?

[CocoaPriest]

You're right, what I mean are annotations. Sorry, didn't see it before.
Simple use-case: an app posts a book review, has some annotations like { "ISBN":"73287328", "Rating":4}
The same app (or whatever client) makes a search for all posts with ISBN=73287328 && Rating > 3

[fields]

Binary payloads would go hand in hand with the idea that certain posts are only meant for certain (or certain groups of) applications.

[ryanschneider]

I'd really like to see private annotations like in #51. Your example of #! /games/chess works for "open" games like chess, but not for asynchornous games like Diplomacy or Apples To Apples, where each player commits to a move, but the moves aren't revealed until all players commit. Being able to add private annotatons that only certain groups/apps/users can see would allow this.

Maybe something like:

{
//...
"annotations": {
        // @user:key annotations are only visible by @user
        "@apples2apples:play-card" : {
            "id" : 1234
        },
        // #!app:key annotations are visible by app
        "#!diplomacy:move" : {
           "army" : "Gal -> Vie"
         },
        // un-prefixed namespaces are public
        "wellknown:geo": {
            "type": "Point",
            "coordinates": [102.0, .5]
        }
    }
//...
}

This would allow games and other apps with non-public information to use app.net as a platform.

[JoshBlake]

@ryanschneider Disagree, permissions on annotations is the wrong scope. It'd be better to simply have permissions on posts, like #33 is discussing, then your game client could sent a private message to the game bot or public comments to other players. I imagine most traditional asymmetrical game mechanics would be better off private messaging a game bot and the game bot rebroadcasting subsets of the message (commentary, or partial information states) to other game player clients.

[markwilcox]

I'm in complete agreement with @JoshBlake on this one. I'd thought about Diplomacy (and similar games) specifically as a use case and concluded it would be best to do them via game bots. Architecturally I think having private parts of a public post is going to get very messy very fast.

I like the concept of per user/group and per "post type" or "protocol" access control that is evolving in #33.

[ryanschneider]

Yup #33 seems to meet my needs as well. My key requirements are structured data (which annotations offer) and limited visibility, which 33 offers and I agree sounds easier to architect.

On Aug 14, 2012, at 6:57 AM, Mark Wilcox notifications@github.com wrote:

I'm in complete agreement with @JoshBlake on this one. I'd thought about Diplomacy (and similar games) specifically as a use case and concluded it would be best to do them via game bots. Architecturally I think having private parts of a public post is going to get very messy very fast.

I like the concept of per user/group and per "post type" or "protocol" access control that is evolving in #33.

�
Reply to this email directly or view it on GitHub.

[rrbrambley]

@fields I agree with the binary payloads concept. This would essentially create unlimited possibilities for the types of posts, and built on top of a solution that addresses #33, we have a hugely robust API that would enable apps to format data however they want.

[markwilcox]

@rrbrambley @fields JSON does't support binary payloads directly. They were very much included in my original thinking here but you have to base64 encode or similar on the client side.

[thingsinjars]

Is there any more movement around this? Particularly in relation to referenced issue #60 - headless peeps?

Non-text posts seem to be such an important step but the spec doesn't appear to have advanced much in that area in the last couple of weeks. Unless I've missed a discussion in another thread, of course.