Re: reusing Vocabulary terms in Social API (Hypermedia)

I spent some time recently to understand what REST and HATEOS really are 
about and that is the background for the few comments below. 

Evan Prodromou wrote:
> 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.

Yes, but the companies controlling these proprietary APIs generally are 
interested in lock-in, not in improving the web or in defending openness. 
That is one reason why we have countless different "Web APIs" and in 2015 
still need to waste huge amounts of developer time in writing clients from 
scratch again and again instead of using machine readable API 
specifications. 

> 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.

Maybe it makes sense to specify this for the server, maybe not. In any case 
it would help to provide the client with machine readable information about 
this. Requirements for clients and servers can be different. 

> 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.

A generic JSON-LD client (which does not know anything about the Social 
domain) will not know that if this information is not made available in a 
machine readable format. 

> 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.

Premature optimization. 

> 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.

Agreed, that is a dynamic which we should be well aware of. Thanks for 
stressing this. 

Please do not let us throw things under busses. Sometimes people are hurt 
when that happens. 

Cheers,
Andreas

Received on Wednesday, 28 January 2015 06:30:49 UTC