REST endpoints documentation

[DamonOehlman]

First - thanks for releasing this. Of all the WebRTC gateways that have been released this is the most exciting so far IMO (modular architecture, lightweight implementation, etc). At least from my early look...

I was just wondering whether there was anywhere that the actual REST endpoints for the /janus services are documented. While I think having the JS library is a good idea, I'm pretty keen to drive janus from node so will be manually triggering a lot of stuff there.

If the documentation doesn't exist already, I'm probably going to be compiling some of this information from monitoring network traffic and looking through the source so if you would like me to include this in the wiki or something then I'd be more than happy to do that.

Cheers,
Damon.

[meetecho]

Hi Damon,

this is Lorenzo, we met in San Francisco for FOMS in November, nice to see you see potential in this project! A REST documentation is definitely a good suggestion, we'll start preparing one right away.

Just to give you an idea of how it works (I'll add details in the documentation itself), the endpoints you refer to are basically 3:

1. the gateway root (/janus by default, but configurable), which you only POST to in order to create a gateway session;
2. a gateway session endpoint (e.g., /janus/12345678, using the identifier retrieved with the previous create), which you either send a GET to (long poll for events and messages from plugins) or a POST (to create plugin handles or manipulate the session);
3. a plugin handle endpoint (e.g., /janus/12345678/98765432, appending the handle identifier to the session one) which you only send POST messages to (messages/negotiations for a plugin, handle manipulation), as all events related to this handle would be received in the session endpoint GET (our library then redirects the incoming messages to the right handle internally).

The messages that flow around are JSON-based, and have a simple syntax for creating/destroying sessions and handles, and for describing messages and negotiation.

I'll provide more details in the next commit, but feel free to ask for more clarifications in the meanwhile if needed.

Lorenzo

[DamonOehlman]

Hey Lorenzo - Yeah I remember meeting you there :)

Thanks for the info so far, I've made some good progress using the demos to get an idea of what is going on and made some reasonable progress on a module that we'll release as part of the rtc.io suite that will help to interface with Janus. After I've had a chat with Silvia tomorrow (Sydney time) I'll push something up to github.

Cheers,
Damon.

[meetecho]

Damon,

that would be great indeed, thanks for that! Keep us posted :-)

[meetecho]

FYI, I've just added the documentation to doxygen. You can read it online here:

http://janus.conf.meetecho.com/docs/rest.html

If it's not clear enough, let me know and I'll try and improve it.

[DamonOehlman]

Thanks heaps Lorenzo - the docs look excellent, but if I come across anything I'll let you know.

Cheers,
Damon.

[DamonOehlman]

Just wondering how ice candidates are communicated from Janus to the client. I can see in the streaming test example (and in the docs) that SDP is communicated through the jsep attribute in event responses.

At this stage though I can't see how ice candidates are communicated back. Any tips?

[DamonOehlman]

I think I'm showing that I spend most of my time with the browser apis with that last question, and from the stuff I've been having a look at today I think the ice candidates are communicated in the sdp. Is this correct?

[meetecho]

Yes, ICE candidates are communicated in the SDP as part of the negotiation process. In particular, they are sent in the "jsep" field of messages addressed to a plugin, or in events that the plugin sends to you (and to which the gateway attaches the "jsep", as plugins don't handle candidates themselves).

We're of course planning to support Trickle ICE as well in next versions (that is, where you send an SDP without candidates right away and then only the candidates when they're available), but right now the idea was to keep it simple and wait for the candidates to be all available before sending the SDP. In fact, only Chrome supports it right now (even though I know Firefox is working on it), which made things simpler in JavaScript too.