Re: reusing Vocabulary terms in Social API (Hypermedia)

I am not crazy about this approach.

I mentioned today that most proprietary APIs don't follow this principle 
(Facebook might be a notable example). They instead have documented URI 
patterns that developers can use to query the data they want.

Beside that, I think that client developers aren't idiots. They will see 
that if they want to get to your list of friends, all they have to do is 
append "/friends" to the URL they used to retrieve your profile data. It 
just doesn't make sense for them to do 2 HTTP requests to the API and 
parse through the links information when they know very well exactly 
where your friends stream is going to be.

Doing that each time they want to retrieve the events you organized, or 
the groups you're a member of, or whatever, is really a hassle. They 
either need to cache those links on the client side -- with all the 
complications that has -- or re-retrieve your profile data over and over 
again. Imagine retrieving and caching thousands or millions of profile 
documents just because you don't want to "assume" that the friends 
document will be exactly where you know it will be.

Once enough client programmers use the "short cut" of following URI 
patterns, there will be pressure on other server implementers to 
implement the same pattern. Especially if there are some platforms that 
are more popular than others! The less popular platforms will use the 
same URI patterns as the more popular platforms in order to assure 
client software compatibility.

At this point, we'd have a /de facto/ URI pattern standard, undocumented 
or poorly documented, that everyone would have to use.

And what do we gain by not specifying a URI pattern for our endpoints?

 1. The moral high ground.
 2. The option for server implementers to make up any kind of
    crazy-pants URI format they want.

Those seem pretty reasonable things to throw under the bus in exchange 
for a) performance and b) familiarity to developers.

-Evan

On 2015-01-21 03:14 PM, ☮ elf Pavlik ☮ wrote:
> Hello,
>
> Since we start clarifying our direction in Social API, I would like to
> discuss leveraging *terms* which we find in existing vocabularies and
> new one's which we work on.
>
> First I will make short detour. In Architecture of the World Wide Web,
> Volume One we find:
>
>      Good practice: URI opacity
>
>      Agents making use of URIs SHOULD NOT attempt to infer properties
>      of the referenced resource.
>
> http://www.w3.org/TR/webarch/#uri-opacity
>
> In context of our work I would interpret it as:
> "Since URIs should stay opaque, we SHOULD NOT mandate what to include in
> URIs denoting resource in API - no *magic* paths!"
>
> If someone wants to expose all the resources using URIs like
>
> * https://example.com/c251a9aa-bf89-466f-a8d5-a18ea5377f70
> * https://example.com/18d96e54-cfb6-4d14-bef0-80addf21e7a2
> * https://example.com/58438e23-fe45-4589-8ecb-43a459da075a
>
> Everything should still work :)
>
>
> How do we find then things like: *list of elf's friends*?
>
> HYPERMEDIA to the rescue \o/
>
> Many people feel quite comfortable with *link relations*. When someone
> publishes and article with multiple pages. This person doesn't need to
> follow conventions like: "For second page add /2 to your URL" etc.
> Once we fetch (dereference) given web page, we can simple search for
> links with rel="next" or rel="prev" leaving publisher freedom to use
> whatever they want in their URLs.
> One can find many more such link relations on microformats wiki,
> referenced in official HTML5 spec!
> http://microformats.org/wiki/existing-rel-values
>
> In similar way everyone could find list of my friends. Once someone
> fetches (dereferences) my online profile, could search in it for links
> with rel="knows" or rel="follows". Actually RDFa reuses rel attribute
> and we can also use similar pattern in JSON-LD or turtle.
> (we can find relation/property/predicate *knows* in FOAF or schema.org!)
>
> Since I know few thousands of people, and other people find themselves
> followed online even by millions of other people. We need a way to avoid
> publishing all those links directly on our homepage! One of the proposed
> solutions comes from Hydra CG -
> https://www.w3.org/community/hydra/wiki/Collection_Design
>
> {
>    "@context": {
>      "@vocab": "http://schema.org",
>      "hydra": "http://www.w3.org/ns/hydra/core#"
>    },
>    "@id": "https://wwelves.org/perpetual-tripper",
>    "name": "elf Pavlik",
>    "hydra:collection": [
>      {
>        "@id": "https://wwelves.org/perpetual-tripper/friends",
>        "name": "elf Pavlik's friends",
>        "hydra:manages": {
>          "property": "knows",
>          "subject": "https://wwelves.org/perpetual-tripper/friends"
>        }
>      },
>      {
>        "@id": "https://wwelves.org/perpetual-tripper/events",
>        "name": "elf Pavlik's events",
>        "hydra:manages": {
>          "property": "attendee",
>          "object": "https://wwelves.org/perpetual-tripper/friends"
>        }
>      }
>    ]
> }
>
> Even that I chose to use vanity URLs ending with /friends or /events, I
> could as well use generic /c251a9aa-bf89-466f-a8d5-a18ea5377f70 and it
> will still work. If you read this example carefully you would notice
> that I even used attendee relation/property/predicate in *inverse*
> direction :)
>
> I will leave it here and I hope we can discuss together various
> advantages, and possible drawbacks of such approach...
>
> Cheers :)
>