Re: 2 APIs and the charter

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.

cheers,

dret.

-- 
erik wilde | mailto:dret@berkeley.edu  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

Received on Thursday, 12 February 2015 00:05:08 UTC