Re: reusing Vocabulary terms in Social API (Hypermedia)

As some slight pushback, you also lose the ability to:

* Implement using or on top of existing systems with colliding or otherwise
incompatible URIs
* Interoperate with other standards that have made incompatible URI
decisions

For example, say (person)/friends is the mandatory URI pattern for the list
of friends, and (person) can be any URI.  That would be hard to reconcile
with LDP Containers that (for all intents and purposes) must end in a / to
allow for sane relative URIs, that otherwise might be used to create
friendship links.

Now fast forward to when there are 15 standards in the same overlapping
space, all specifying mandatory URI patterns and you have a mess.

[Yes, for LDP, you could have a DirectContainer with a membershipResource
of /friends but now you have two problems without regular expressions]

Throwing out the fundamentals of the web architecture should be a step
taken only with caution for well justified reasons, rather than for simple
expedience.

On your two points:
* Simplicity: Client developers are not idiots :)
* Performance: Premature optimization is the root of all evil.

Best regards,

Rob


On Tue, Jan 27, 2015 at 1:50 PM, Evan Prodromou <evan@e14n.com> wrote:

>  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" <http://schema.org>,
>     "hydra": "http://www.w3.org/ns/hydra/core#" <http://www.w3.org/ns/hydra/core#>
>   },
>   "@id": "https://wwelves.org/perpetual-tripper" <https://wwelves.org/perpetual-tripper>,
>   "name": "elf Pavlik",
>   "hydra:collection": [
>     {
>       "@id": "https://wwelves.org/perpetual-tripper/friends" <https://wwelves.org/perpetual-tripper/friends>,
>       "name": "elf Pavlik's friends",
>       "hydra:manages": {
>         "property": "knows",
>         "subject": "https://wwelves.org/perpetual-tripper/friends" <https://wwelves.org/perpetual-tripper/friends>
>       }
>     },
>     {
>       "@id": "https://wwelves.org/perpetual-tripper/events" <https://wwelves.org/perpetual-tripper/events>,
>       "name": "elf Pavlik's events",
>       "hydra:manages": {
>         "property": "attendee",
>         "object": "https://wwelves.org/perpetual-tripper/friends" <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 :)
>
>
>
>


-- 
Rob Sanderson
Information Standards Advocate
Digital Library Systems and Services
Stanford, CA 94305