Re: reusing Vocabulary terms in Social API (Hypermedia)

On 01/27/2015 10:50 PM, Evan Prodromou 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.

In general while I think we can agree generically URI opacity is a good
thing, it's not necessarily required - as most real-world APIs we've
looked at so far are obviously not opaque.

White it is advise from the TAG quite a number of years ago, it not
necessarily required. I do hope our API will also go through a TAG
review, and the TAG is now much more dominated by Javascript API
specialists with extensive real-world experience in API design than
Semantic Web specialists.

Thus, I suggest that whoever whiteboards the API be allowed to violate
URI opacity if they feel it's necessary or makes life easier for
developers. However, if a version of the API that uses opaque URIs is
thought and is acceptable to real-world products and developers, it can
of course be compared and contrasted, and through some evolutionary back
and forth with the WG the best possible API will no doubt emerge.

The next step after empirical work has been done is to whiteboard the
API obviously. It can even be possible to have multiple whiteboarded APIs.

Maybe a good next step would be to determine what parts are not covered
by the ActivityStreams proposal from OpenSocial?

> 
> -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 :)
>>
> 
>

Received on Thursday, 29 January 2015 11:36:26 UTC