Re: Proposal: Different specifications for different target audiences

Roman,

     I think we are actually in agreement.

     I accept your approach for the low-level API (it is a good fit!) 
but not for the high-level one. If you consider:

http://lcsd05.cs.tamu.edu/slides/keynote.pdf:

  * Slide 14: "API Should be as small as possible but no smaller"
  * Slide 15: "Implementation should not impact API"
  * Slide 28: "Don't make the client do anything the module could do"

     I argue that there are API methods that would be "implementation 
details" or "making the client do something the module should do" for 
Web Developers but not Integrators. By giving each stakeholder type a 
different API everyone gets the right level of detail.

     Whether you realize it or not, you are saying the same thing. You 
wrote: "For users with common use cases you create javascript libraries 
that implement them." That's is precisely what I meant by the high-level 
API.

Gili

On 19/07/2013 2:13 PM, Roman Shpount wrote:
> I have mentioned this previously but I dislike this approach. As far 
> as I am concerned there is no difference between integrators and web 
> developers. The reason current API is so difficult to use is that it 
> uses terms and abstractions that have very little relationship with 
> either underlying capabilities or desired functionality.
>
> So, my approach to API design would be different:
>
> a. Determine the underlying functionality based on use cases. You 
> never define API methods based on use cases, this is bad design. You 
> define capabilities. These would be things like I should be able to 
> send audio and video over DTLS-SRTP, data over SCTP over DTLS for 
> data, etc
>
> b. Create the API that provides complete control of the underlying 
> capabilities at the lowest possible level without sacrificing overall 
> security or performance. You want to expose all the system 
> capabilities as close to the bare metal as possible with only possible 
> restrictions being security (no raw socket access from browser 
> javascript) and performance (no javascript codecs, at least not yet). 
> API should give access to all system functionality regardless of the 
> use case which will require such access. There should be concrete 
> security or performance reason to deny access to features. This API 
> should also be testable and unambiguously predictable (which is much 
> more important then extendable API), so no string blob or dictionary 
> interfaces.
>
> c. For users with common use cases you create javascript libraries 
> that implement them.
>
> As a result we will have capabilities to address all the use cases, 
> browser implementers will need to create as little code as possible, 
> and application developers will be in control of their own destiny.
>
> All of this being said, this is all wishful thinking. Right now I 
> would settle for a predictable and testable API with functionality 
> currently available in the browsers.
> _____________
> Roman Shpount
>