Subject: [rtcweb] API draft: draft-kaplan-rtcweb-api-reqs-00

From: Hadriel Kaplan <[email-masked]>
Date: Fri, 21 Oct 2011 09:39:16 +0000

Howdy,
we've posted an initial strawman for "API requirements" for "no signaling" as our chairs have asked for for the con call.
I'm still not sure why we need to provide this in an I-D, but given only a few days notice and having other day jobs, we've tried our best in the short timeframe.

Note: given the announced conf call for Friday (today?), I've submitted this version without getting final proof-reading from the other authors.  So some new bits I wrote they may not agree with... in fact some bits I wrote *I* may not agree with, given how late it is at night for me (well I guess early in the morning technically).  Caveat emptor. :)

Link details below.

A New Internet-Draft is available from the on-line Internet-Drafts directories.

	Title           : API Requirements for RTCWEB-enabled Browsers
	Author(s)       : Hadriel Kaplan
                         Dan Burnett
                         Neil Stratford
                         Tim Panton
	Filename        : draft-kaplan-rtcweb-api-reqs-00.txt
	Pages           : 13
	Date            : 2011-10-21

  This document discusses the advantages and disadvantages of several
  proposed approaches to what type of API and architectural model
  RTCWeb Browsers should expose and use.  The document then defines
  the requirements for an API that treats the Browser as a library and
  interface as opposed to a self-contained application agent.

A URL for this Internet-Draft is:
http://www.ietf.org/internet-drafts/draft-kaplan-rtcweb-api-reqs-00.txt

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

This Internet-Draft can be retrieved at:
ftp://ftp.ietf.org/internet-drafts/draft-kaplan-rtcweb-api-reqs-00.txt

---

From: Iñaki Baz Castillo <[email-masked]>
Date: Fri, 21 Oct 2011 13:13:54 +0200

> http://www.ietf.org/internet-drafts/draft-kaplan-rtcweb-api-reqs-00.txt

I love this draft.

Just a comment. The draft says:

---------------------
   There has been discussion that RTCWeb should strive to enable media
   communication session with about "20 lines of code".  We assert the
   only means of achieving that goal in a production-deployment manner
   is to use Javascript, and in particular Javascript libraries.
---------------------

I would like to insist on that. When people says "20 lines of code" I
expect that they mean the number of lines that a *high-user* needs to
write in order to code a RTC session. But I assume that such
*high-user* is using a JS library the browser retrieved from the
website, and that JS library deals with all the complexity at low
level.

So for example, let's take a look to Phono JS library. It does allow
implementing a call in 20 lines of code, but the library itself has
more than 20 lines :)
Anyhow the high-user must only deal with Phono JS API and using such
API can code a call in 20 lines.

That's the point IMHO. Let's the complexity to the developers of JS
libraries, and they will make a simple API for end users. This is how
WWW works and IMHO RTCweb should go in the same direction. We cannot
and must no change WWW.

Best regards.

-- 
Iñaki Baz Castillo
<[email-masked]>

---

From: Magnus Westerlund <[email-masked]>
Date: Fri, 21 Oct 2011 13:21:31 +0200

Thanks Hadriel and your co-authors.

This documents section 5 do show a bit what level of requirements that
arise from this design. The thing I think I am still wondering of is how
to satisfy the timing constraints some of our on the wire protocol puts
on session management in the JS.

I would also have like a bit of discussion of how to arrive at
interoperability as this will be a function of the JS and the server.

But considering the tight timing I appreciate what you produced.

Cheers

Magnus

On 2011-10-21 11:39, Hadriel Kaplan wrote:
> 
> Howdy, we've posted an initial strawman for "API requirements" for
> "no signaling" as our chairs have asked for for the con call. I'm
> still not sure why we need to provide this in an I-D, but given only
> a few days notice and having other day jobs, we've tried our best in
> the short timeframe.
> 
> Note: given the announced conf call for Friday (today?), I've
> submitted this version without getting final proof-reading from the
> other authors.  So some new bits I wrote they may not agree with...
> in fact some bits I wrote *I* may not agree with, given how late it
> is at night for me (well I guess early in the morning technically).
> Caveat emptor. :)
> 
> Link details below.
> 
> 
> Author(s)       : Hadriel Kaplan Dan Burnett Neil Stratford Tim
> Panton Filename        : draft-kaplan-rtcweb-api-reqs-00.txt Pages
> : 13 Date            : 2011-10-21
> 
> RTCWeb Browsers should expose and use.  The document then defines the
> requirements for an API that treats the Browser as a library and 
>  _______________________________________________ rtcweb mailing list 
> [email-masked] https://www.ietf.org/mailman/listinfo/rtcweb
> 

-- 

Magnus Westerlund

----------------------------------------------------------------------
Multimedia Technologies, Ericsson Research EAB/TVM
----------------------------------------------------------------------
Ericsson AB                | Phone  +46 10 7148287
Färögatan 6                | Mobile +46 73 0949079
SE-164 80 Stockholm, Sweden| mailto: [email-masked]
----------------------------------------------------------------------

---

From: Christer Holmberg <[email-masked]>
Date: Fri, 21 Oct 2011 13:22:30 +0200

Hi,

I am not sure I understand.

We need to specify what is to be used by the JS library developers. If they then design libraries that allow people to set up calls using 20 lines of code, fine, but how can WE enforce that to happen?

I don't think we can say that the API WE specify shall allow setting up a call using 20 lines. We can only hope (and, of course, do whatever we can do in order to allow that to happen) that the API WE specify allows someone ELSE to produce a library which then allows users to set up calls using 20 lines :)

Or?

Regards,

Christer 

> -----Original Message-----
> From: [email-masked] 
> [mailto:[email-masked]] On Behalf Of Iñaki Baz Castillo
> Sent: 21. lokakuuta 2011 14:14
> To: Hadriel Kaplan
> Cc: <[email-masked]>
> Subject: Re: [rtcweb] API draft: draft-kaplan-rtcweb-api-reqs-00
> 
> I would like to insist on that. When people says "20 lines of 
> code" I expect that they mean the number of lines that a 
> *high-user* needs to write in order to code a RTC session. 
> But I assume that such
> *high-user* is using a JS library the browser retrieved from 
> the website, and that JS library deals with all the 
> complexity at low level.
> 
> So for example, let's take a look to Phono JS library. It 
> does allow implementing a call in 20 lines of code, but the 
> library itself has more than 20 lines :) Anyhow the high-user 
> must only deal with Phono JS API and using such API can code 
> a call in 20 lines.
> 
> That's the point IMHO. Let's the complexity to the developers 
> of JS libraries, and they will make a simple API for end 
> users. This is how WWW works and IMHO RTCweb should go in the 
> same direction. We cannot and must no change WWW.
> 
> Best regards.
> 
> 
> --
> Iñaki Baz Castillo
> <[email-masked]>
> [email-masked]
> https://www.ietf.org/mailman/listinfo/rtcweb
>

---

From: Iñaki Baz Castillo <[email-masked]>
Date: Fri, 21 Oct 2011 13:24:34 +0200

> I don't think we can say that the API WE specify shall allow setting up a call using 20 lines. We can only hope (and, of course, do whatever we can do in order to allow that to happen) that the API…

That's exactly what I meant :)

-- 
Iñaki Baz Castillo
<[email-masked]>

---

From: Harald Alvestrand <[email-masked]>
Date: Fri, 21 Oct 2011 13:40:33 +0200

> Note: given the announced conf call for Friday (today?), I've submitted this version without getting final proof-reading from the other authors.  So some new bits I wrote they may not agree with...…
Thank you, this document was most informative to me, and illustrated the 
position taken well (although I disagree with its conclusions).

It also served very nicely to illustrate the breadth of functionality 
that a "low level API" needs to expose.

One note (speaking as a W3C WG chair): While it's very nice to imagine 
that one can toss a task like "design an API" over to another 
organization and having it performed, in practice, the W3C functions 
much like the IETF; it's not a place where you throw work in order to 
get work done, it's a place where people who need the work done go to 
work on the problem.

But we all knew that, I think....

---

From: Dan Burnett <[email-masked]>
Date: Fri, 21 Oct 2011 08:14:45 -0400

On Oct 21, 2011, at 7:40 AM, Harald Alvestrand wrote:

> Thank you, this document was most informative to me, and illustrated the position taken well (although I disagree with its conclusions).
> 
> It also served very nicely to illustrate the breadth of functionality that a "low level API" needs to expose.
> 
> One note (speaking as a W3C WG chair): While it's very nice to imagine that one can toss a task like "design an API" over to another organization and having it performed, in practice, the W3C functions much like the IETF; it's not a place where you throw work in order to get work done, it's a place where people who need the work done go to work on the problem.

And speaking as an editor in the W3C group to which you are referring, the point here is that protocol discussions are leading API discussions, and both are happening in the RTCWeb group, when the API discussions should all be happening in the W3C WebRTC group.  But, since JS API discussions are happening here, we now have a "no-signaling" draft in the IETF that lists requirements on the WebRTC API, *because the chairs asked for it*.

---

From: Harald Alvestrand <[email-masked]>
Date: Fri, 21 Oct 2011 14:27:49 +0200

> And speaking as an editor in the W3C group to which you are referring, the point here is that protocol discussions are leading API discussions, and both are happening in the RTCWeb group, when the…
sorry, not my intention to sound critical of the people that have 
volunteered already...

what I was reacting to was the statement in the draft that said

> 5.6. API Design Recommendations
>
>    Technically the API design is the role of the W3C.  That hasn't
>    stopped people in the IETF RTCWEB mailing list from discussing it ad
>    nauseum, however, and even defining a protocol for it.  This
>    document therefore recommends the following to W3C:
..........
>
>    4) That when a IETF documents start telling you how to build
>      Javascript APIs, you should run far away... quickly.  :)

which SOUNDED like the requirements here were being "tossed over the wall".
I know that both you and Neil have worked on this on the "W3C side", too!

                  Harald

(Parenthesis: My current understanding is that the W3C group is going to 
create the API that fits what the IETF says should be the model - which 
depends, in part, on the result of this discussion.)

---

From: Iñaki Baz Castillo <[email-masked]>
Date: Fri, 21 Oct 2011 14:30:37 +0200

> And speaking as an editor in the W3C group to which you are referring, the point here is that protocol discussions are leading API discussions, and both are happening in the RTCWeb group, when the…

Hi Dan, I understand your point but please consider that this WG has
been involved in a discussion about the scope of such WebRTC API. It's
still unclear/undefined whether such API must only deal with media
aspects of the RTCweb stack in the browser, or whether it must also
deal with external signaling (in-the-wire).

Honestly I think that current works and proposals are helping a lot
for us to understand the whole picture. However I don't think that
this WG is attempting to define such API (which is a task of W3C) but
just to define its scope.

Regards.

-- 
Iñaki Baz Castillo
<[email-masked]>

---

From: Dan York <[email-masked]>
Date: Fri, 21 Oct 2011 08:52:11 -0400

Hadriel (and your co-authors),

Excellent document!  Thanks for taking the time to write this.

Dan (not-ranting-today)

> Note: given the announced conf call for Friday (today?), I've submitted this version without getting final proof-reading from the other authors.  So some new bits I wrote they may not agree with...…

http://tools.ietf.org/html/draft-kaplan-rtcweb-api-reqs

-- 
Dan York  [email-masked]
http://www.danyork.com/   skype:danyork
Phone: +1-802-735-1624
Twitter - http://twitter.com/danyork
--------------------------------------------------------
All comments and opinions are entirely my own and have no connection whatsoever to any employer, past or present. Indeed, by tomorrow even I might be disavowing these comments.
--------------------------------------------------------

---

From: Dan York <[email-masked]>
Date: Fri, 21 Oct 2011 08:55:58 -0400

Bingo... I think we want to create the conditions where a hundred different JavaScript libraries will bloom as developers try out new and innovative ways to bring real-time communications directly into the web browsers and weave it into the fabric of the web.

Yes, some (many? most?) of those libraries will suck badly ... but over time I believe the "jQuery of RTCWEB" will emerge from somewhere and suddenly people all over will be baking RTC directly into web apps using the proverbial less than 20 lines of code.

My 2 cents,
Dan

---

From: Hadriel Kaplan <[email-masked]>
Date: Fri, 21 Oct 2011 13:00:10 +0000

> It also served very nicely to illustrate the breadth of functionality that a "low level API" needs to expose.

Actually I'm 100% sure I've forgotten/missed some things it needs to expose.  BUT, some of the things I listed need to be exposed even for a ROAP model, yet for some reason aren't in the WG use-case-and-requirements draft; and some  already exist exposed in the current W3C draft I think.

> But we all knew that, I think….

Actually I don't know anything about the W3C.  What I meant in the draft by saying "it's really up to W3C" was that I thought it was highly presumptuous of us in the IETF to tell the W3C what to do as the API.  I figured they do APIs for a living, while IETF does protocols for a living. (which might explain why we're now talking in the IETF about defining a protocol as an API, eh? ;)

-hadriel

---

From: Iñaki Baz Castillo <[email-masked]>
Date: Fri, 21 Oct 2011 15:10:04 +0200

2011/10/21 Dan York <[email-masked]>:
> Bingo... I think we want to create the conditions where a hundred different
> JavaScript libraries will bloom as developers try out new and innovative
> ways to bring real-time communications directly into the web browsers and
> weave it into the fabric of the web.

> Yes, some (many? most?) of those libraries will suck badly ... but over time
> I believe the "jQuery of RTCWEB" will emerge from somewhere and suddenly
> people all over will be baking RTC directly into web apps using the
> proverbial less than 20 lines of code.

Hope we *all* agree on this since this is the ONLY way to go in WWW
world (IMHO). It's time to move on and avoid useless discussions about
signaling protocols in the wire.

In summary:

1) Let the browser vendors to be that: "browser vendors". Don't force
them to be SIP/VoIP experts. Well, they must deal with ICE/TURN/RTP,
but that's unavoidable in RTC and this is about RTC.

2) Let the complexity and innovation to the developers who build
JavaScript libraries implementing all the low level stuff and their
own custom singaling protocol in-the-wire (of course with the
colaboration of the web/websocket server, which must implement such
protocol in some language).

3) Let the end users to make use of the libraries provided in point 2,
so they can write a RTC code "in 20 lines".

Point 2 means that all the innovation and quality depends on
JavaScript (in browser side) and PHP/Ruby/Python/Java/.Net/[...] in
server side. This is freedom. Point 3 means success. This is the key
in WWW.

-- 
Iñaki Baz Castillo
<[email-masked]>

---

From: <[email-masked]>
Date: Fri, 21 Oct 2011 15:24:17 +0200

Hi Hadriel & al,

Thanks for this draft and the effort in having it so quickly released. I share your views in trying to keep the service logic as much as possible within the server. 

Here are below a few comments that hopefully will help:

- Regarding the interoperability issues that can be faced when using SDP O/A model (§3.7), we can probably explicitly mention the ambiguity and the potential vendor's implementations variations when the orders of the same codec are inversed in the offer and in the answer, as well as when payload types vary for the same codec, or when paquetization differs for the same codec, ..     
- Regarding §5.2, I guess the WEB API, in addition to the codec capabilities, MUST also provide a means to learn about the limitations codec use/combinations can put as a constraint to the browser
- Regarding §5.2, it would be suitable to set/get the jitter buffer characteristics (e.g. for QoS perspectives)
- Regarding A2-4, it would be nice to get also the paquetization/bitrate supported by codecs (e.g. to allow an easy reduction of the required bandwidth)
- Regarding A3-7, if you assume SDES could be used, it is probably TBD (just like A3-6). Same remark regarding A3-8, it is then probably TBD
- Regarding 5.3, in addition to the existing requirements, it would be nice to get the RTCP stats (packet loss, jitter, ..) as well as potential RTP notifications (such as when receiving DTMF event or maybe inband codec modification) but it is very linked to the scoped use cases.
- Regarding 5.3, probably TBD, it could be worth getting the RTP/RTCP capabilities: for instance, the supported profiles, if multipath-RTP gets supported, ..
- Regarding A5-10, in addition it would be nice to get the browser's device network attachment capabilities: for instance, whether multiple NIC exists, if multi-path TCP gets supported, ..

These are probably not exhaustive, are made a bit in a hurry and would certainly benefit from double-crossing them with draft-rtcweb-requirements..

Kind regards
Sebastien

-----Message d'origine-----
De : [email-masked] [mailto:[email-masked]] De la part de Hadriel Kaplan
Envoyé : vendredi 21 octobre 2011 11:39
À : <[email-masked]>
Objet : [rtcweb] API draft: draft-kaplan-rtcweb-api-reqs-00

Howdy,

Link details below.

_______________________________________________
rtcweb mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/rtcweb

---

From: Harald Alvestrand <[email-masked]>
Date: Fri, 21 Oct 2011 15:39:34 +0200

> Actually I'm 100% sure I've forgotten/missed some things it needs to expose.  BUT, some of the things I listed need to be exposed even for a ROAP model, yet for some reason aren't in the WG use-cas…
I'm sure. The use cases are relatively high level, much higher level 
than the APIs and protocols.

For those you see missing, it would be a good exercise to follow the 
object to "how can I describe the use case in which this is essential", 
and see if it maps to any of the current use cases, or needs to be added.
We've  done several wrinkles on the use cases in order to expose a 
specific requirement - for instance, the need to operate when one or 
both of the participants is behind a NAT box or a 3G mobile connection.
> Actually I don't know anything about the W3C.  What I meant in the draft by saying "it's really up to W3C" was that I thought it was highly presumptuous of us in the IETF to tell the W3C what to do…
I think getting them right requires a huge amount of information 
exchange .... in the W3C community, I see arguments about the dearth of 
good API designers too, and designing an API without understanding the 
underlying technology is just very unlikely to succeed.

Luckily, we've got people (usually members of both lists) who are 
implementing this even as we speak; they might get enough feedback into 
the loop eventually.

                 Harald