Re: 2 APIs and the charter

On 02/11/2015 07:04 PM, Erik Wilde wrote:
> hello henry.
>
> On 2015-02-11 15:44 , henry.story@bblfish.net wrote:
>> The Working group charter [0] currently calls for 2 APIs
>> I am having trouble parsing what these APIs are meant to do.
>>
>> the social API
>> --------------
>> I read:
>> "defines a specification for a client-side API that lets developers 
>> embed and format third party information such as social status 
>> updates inside Web applications."
>> This is pretty much unparseable to me. You need to look at the 
>> example Open Social 2.5.1 Activity Streams and Embedded Experiences 
>> API to get an idea of what is meant. It is just simply a subset of 
>> HTTP with information of how you can GET information about a 
>> resource, how you can create a resource ( POST ), how you can update 
>> an entry ( PUT ), etc...
>> What does this have to do essentially with Web Applications? And why 
>> is this client side? What seems to be meant here is browser only. But 
>> why could a "server" not also get the information published in an  
>> activity stream?
>> In my view being a client and a server is just a role. You are a 
>> client if you initiate an HTTP Connection, you are a server if you 
>> receive a connection.
>> What seems to be meant here is an API for reading, updating, creating 
>> and deleting a number of information resources containing social data 
>> ( and of course content such as pictures ). One determining 
>> application of this API is that thick clients  ( eg mobile 
>> applications ) should then be written tht can display this 
>> information to the human user so that he can then do a number of 
>> actions described in the  user stories. But of course a web server 
>> could also get this information and create a static page to display 
>> it, or use it to run a statistical algorithm on it.
>> If that is the right interpretation then oddly enough that is exactly 
>> what I do using what is termed the "Federation Protocol". I have a JS 
>> client in the browser that fetches data from an LDP servers (GET), 
>> updates it (PATCH), delete's resources ( DELTE ), etc...  see below.
>
> i completely agree that it probably isn't the greatest or clearest 
> charter ever written. my exegesis of this part initially was that it 
> was written with maybe an API in the HTML5 sense of the word in mind: 
> a DOM API that applications then can use through traditional API 
> mechanisms (i.e., local function call) .
>
> we had discussions around this at the santa clara f2f and thankfully 
> agreed that this first part should *not* be read as a mandate for such 
> a DOM-based API, but instead should be read as asking for an HTTP API.
>
> to me, this also meant that the distinction between the 2 APIs pretty 
> much went away, because i always read the charter as being written 
> with this (1) a DOM API and (2) an HTTP API separation in mind. so i 
> was happy that the WG decided in santa clara that we actually wanted 
> an HTTP API. we delayed the decision about what that would actually 
> mean in terms of now being chartered with creating 2 HTTP APIs.
>
> i am completely with you that i cannot really imagine what those two 
> APIs would look like, and why you would want to have two. if we build 
> a proper REST API then interactions are driven be links anyway and 
> implementations are free to not implement certain resources if they 
> choose to do so (and then certain links will not show up and all 
> clients still can happily follow those links that do show up).
>
> well, i guess none of this really explains anything in terms of deeper 
> charter exegesis, but that's how i have come to read it, how i think 
> it makes sense given our santa clara discussions, and how i think we 
> will end up understanding that both APIs are one. and we will simply 
> make sure that not all implementations have to implement the full API 
> (all resources of it) and that's just fine; it's still just one API.
>

I agree with your reading of the charter, etc, but I think it still 
makes sense to imagine two distinct APIs.

I imagine Alice running software that talks to ServerA and Bob running 
software that perhaps connects to ServerB.   I see a client-server 
protocol (the "Social API" in the charter) as what Alice's and Bob's 
client software uses to talk to their respective servers.  I see a 
different server-server protocol used between ServerA and ServerB, to 
allow Alice and Bob to interact, even though they are using different 
servers.    This is the "Federation Protocol" in the charter.

Now, I expect both protocols will be very similar, consisting of HTTP 
operations on pretty much the same kind of objects, but I expect the 
server-server protocol will have somewhat different notions of 
authentication, and other issues that come up in a multi-user context.

It might be possible to make do without any server-server protocol, by 
having Alice's software talk to ServerB sometimes and Bob's software 
talk to ServerA sometimes.  This is what we did with Cimba.   But we ran 
into some problems, and I'm not convinced it's possible to make this 
scale well enough, so I wouldn't want to rule out having a server-server 
protocol.

In short, let's try to make a good and natural client-server protocol, 
and if it then turns out we don't need to do anything else for a 
server-server protocol, then great.     If we need to tweak it a little 
for server-server, that's fine.   If it turns out we need something 
completely different, that's not the end of the world either.

       -- Sandro




> cheers,
>
> dret.
>

Received on Thursday, 12 February 2015 01:54:05 UTC