Cost of interop with existing systems is high

[sandeepshetty]

Most HTTP APIs are meant for clients to interact with web applications. tent.io is different in that it has a HTTP API that your application must expose if it wants to "participate" in the tent.io version of the Federated/Decentralized Social Web.

This approach is problematic for two primary reasons:

1. If an existing service wants to support these "protocols" they need to surrender a part of their URI space, and
2. Be forced to maintain a parallel URI space for things that are already modeled in their system.

While this approach might be ideal for a cleanroom environment, it's inappropriate for the chaotic and complex web that exists today as the cost of interop with existing systems is high.

Is this intentional?

[elimisteve]

@sandeepshetty I partially get where you're coming from. Can you give an example of an API that you think Tent's should resemble more closely?

[sandeepshetty]

The problem stems from the fact that HTTP specifies application-level semantics which in this case would be fine if you were building just another Tent server.

If the endpoints were instead discoverable (Link header/element, hypertext), implementations would have the freedom to control their own URI space. Salmon and PubSubHubbub are examples of protocols that don't invade your URI space.

[melvincarvalho]

@sandeepshetty

This is an interesting point.

If I have understood correctly, you are suggesting that "follow your nose" (link following) style search/discovery has advantages over the "well known" path pattern (hard coding a location).

Remember of course that tent is only v0.1 and well known is a practical pattern used by may apis eg twitter to become more established. So it's about pros and cons.

But I understand where you're coming from an engineering/standards perspective. Do you have any specific examples that you find problematic e.g. /following etc.

[elimisteve]

@sandeepshetty "If the endpoints were instead discoverable (Link header/element, hypertext), ..."

curl -v https://tent.tent.is/tent

Part of the output:

Link: </tent/profile>; rel="https://tent.io/rels/profile"

Is that what you had in mind?

[sandeepshetty]

@melvincarvalho The "well know" pattern your talking about is in the context of clients consuming an API, not for server implementors. As an example, If I have an existing social networking service, it's very likely that I already have the /following path mapped in my app. Now, if I need to interop with @tent, I have to either give up that path, overload it or choose not to interop.

@elimisteve Think the profile is already discoverable. Maybe just include the relevant paths/uri-templates (for following, followers and posts) in the profile?

[atd]

Hi, this is an issue I also though about when I first read the @tent specification.

As a Rails developer, I pretty much coincide with the names choosen. But I though that if the names were others, I wish I could use my own Rails conventions.

[mwanji]

@sandeepshetty @elimisteve If all responses included Link headers to the available actions, then actual URLs wouldn't matter anymore. The current URLs could be kept as fallbacks if no such headers are provided. Maybe HAL could be used for more sophisticated descriptions: http://stateless.co/hal_specification.html

[graue]

@sandeepshetty I think you're misunderstanding how the request paths work. And now that I think of it, this is somewhat misleading in the API docs. Where the docs say, for example,

GET /followings

they really mean

GET (API root)/followings

where the API root is given by the server. On Tent.is, the API root is /tent, so you get /tent/followings and so on.

So the following paths all produce HTML to display in your browser, and are 100% defined by the TentStatus app, not the Tent.io protocol (which means they could be anything):

• https://graue.tent.is/profile
• https://graue.tent.is/followings
• https://graue.tent.is/posts/t40wwb

While these paths are all API calls that return JSON:

• https://graue.tent.is/tent/profile
• https://graue.tent.is/tent/followings
• https://graue.tent.is/tent/posts/t40wwb

You can define the API root to be whatever you want, per user. In fact the API doesn't even have to sit on the same server as your webapp. The only limitation is that your API endpoints have to be at a path that ends with /profile, /followings, etc. Beyond that, Tent gives you complete freedom to shuffle things around as you want.

For example, given the entity URI https://updates.tent.is/, if you want to pull recent posts from that user, the flow is:

1. Request https://updates.tent.is/
2. Extract profile link from HTTP link header or HTML tag. In this case it's https://updates.tent.is/tent/profile
3. Request https://updates.tent.is/tent/profile
4. From the JSON result, extract "servers" list which in this case is just https://updates.tent.is/tent
5. Using the previous result as API root, append /posts and get https://updates.tent.is/tent/posts
6. Request https://updates.tent.is/tent/posts, which is the actual post data

It's a complex process, but the only restriction on the path here is that the last request had to end in /posts. That's it. The API root, which was given here as the path /tent, could be anything.

[mwanji]

@graue said: "The only limitation is that your API endpoints have to be at a path that ends with /profile, /followings, etc."

But if we were to use link relations, even that limitation would be lifted. Not sure how crucial it is, but it would be nice.

Also, I hope that the separation on tent.is between the API root (/tent) and the HTML root (/) is an implementation detail. It should be possible to serve JSON and HTML on the same URL, based on Accept headers.

[sandeepshetty]

@graue Still assumes things about the existing system that is trying to interop, like support for clean URLs, which is exclusionary and by virtue not open.

Also, the website IS the API. The difference is only in the representation.

[graue]

@mwanji Pretty sure you can indeed serve JSON & HTML from the same URL depending on Accept headers.

@sandeepshetty What's the practical consequence of requiring "clean URLs"? Even most PHP-based shared hosting allows setting that up now. Other frameworks don't have a concept of "clean URLs" because they don't use a 1:1 URL to file mapping to begin with. And low-traffic personal sites based on those frameworks can be hosted on Heroku for free.

[sandeepshetty]

@graue The little details (forcing implementors to give up control of a part of their URI space, forcing clean URLs, forcing a parallel URI space, tight coupling over a wide-surface-area) are just design smells in the context of existing systems that want to interop.

"Servers must have the freedom to control their own namespace"

[melvincarvalho]

@sandeepshetty I think is right. There's always workarounds to any problem. For example you can easily set a rewrite rule to take the tent content type and route it to a preferred area on your server. BTW 10/10 for putting content type in the spec.

But putting interop first really is the key to giving yourself massive global scalability. I think tent is 90% of the way there tho, but that final 10% can be ever elusive. Getting the seemingly small details right helps.

[sull]

Discoverable endpoints should not be excluded. It is the best approach for loose interop which is what you want in order to get momentum. Over time, you might see more adherence to using well-known paths etc. #Bridges

[titanous]

This has been addressed in #181 and #178.