This is the second blog post in our REST API integration series. In the previous blog post, we explained how to integrate signaling state changes into our REST API. Today, we want to take a closer look at ICE gathering state changes and in the next post, our focus will shift to ICE connection state changes.

Interactive Connectivity Establishment (ICE) in WebRTC

Real-time communication requires a reliable NAT traversal mechanism as the involved endpoints are likely to be behind NATs or firewalls. Thus, the WebRTC Standard makes ICE usage mandatory for all WebRTC endpoints (RFC5245). For real-time applications to track changes in the ICE state machine, WebRTC API exposes two states, ICE gathering state and ICE connection state.

ICE Gathering States in WebRTC

ICE gathering state is used to track the process of collecting local ICE candidates, which precedes ICE connectivity checks. In this process, the WebRTC endpoint discovers all IP addresses under which the remote party can potentially reach it.

To illustrate the process of ICE gathering state transitions, let’s imagine that one of our users Alice is trying to call Bob. We can track the changes of Alice’ ICE gathering state based on WebRTC API calls that she invokes.

Alice starts in the new state when a new PeerConnection is created. Alice starts the conversation by creating an SDP offer (pc.createOffer) and only when she assigns this offer to the PeerConnection (pc.setLocalDescription), the WebRTC stack starts to gather local ICE candidates ( gathering state is reached). After some time, all available local interfaces are discovered and complete ICE gathering state is reached.

Types of ICE Candidates Gathered

Alice can gather three types of ICE candidates; host, server/peer reflexive, and relay candidates.

• Host candidates: are generated by the endpoint by binding its local network interfaces
• Server/Peer reflexive candidate: is obtained by sending request to a STUN server and a combination of public IP address and port returned in the message from the server is used as the candidate
• Relay candidate: is obtained by sending the communication channel allocation request to a TURN server and a combination of public IP address and port representing the channel entrypoint is returned. The TURN server will act as a relay between channel allocated for Alice and the one for Bob.

From the perspective of REST API integration, it is crucial to report all transitions of ICE gathering state through submitting fabric state change. For example if the state transition happens from gathering to complete state happens for Alice, it should be reported by sending following message to:

 {  
  "localID": "Alice",
  "originID": "Alice",
  "remoteID": "Bob",
  "deviceID": "dev-0001",
  "timestamp": 1483228800537,
  "connectionID": "conn-0001",
  "prevState": "gathering",
  "newState": "complete",
  "changedState": "iceGatheringState"
  }

Proper integration of ICE gathering state transitions is vital in enabling callstats.io to do the diagnostics of potential ICE problems that can arise during the call establishment. For a step-by-step instruction on integrating REST API, please have a look at our REST API documentation page.

In the next blog post of this series, we will describe efforts needed to properly integrate REST API with ICE connection state transitions, stay tuned!