Spreed WebRTC REST API v1.0.0
            ===============================================
                        (c)2016 struktur AG

The server provides a REST api end point to provide functionality outside the
the channeling API or without a established web socket connection.

The REST API does always return valid JSON data. This includes the non 200
status responses. If non JSON is received this is an error not generated by the
API or there was a problem while JSON encoding.

Some end points of this API require a existing session from the channeling
API, incuding the private secret session ID. To get these it is sufficient
to connect to the channeling API with a websocket connection. The server
sends the session ID (Id) and secure session ID (Sid) within the Self
document after connection was established.


Available end points with request methods and content-type:

  /.well-known/spreed-configuration

    The well-known end points can be used to discover the base addresses for
    other end points. Spreed WebRTC provides this for compatibility with
    larger setups so clients using this can find the Spreed WebRTC end point.

    GET application/x-www-form-urlencoded
    No parameters.
    Response 200:
      {
        "spreed-webrtc_endpoint": "http://localhost:8093"
      }


  /api/v1/config

    The config end points returns the server configuration. As it is available
    to the Web client.

    GET application/x-www-form-urlencoded
      No parameters.
      Response 200:
        {
          "Title": "Spreed WebRTC",
          "S": "static/ver=1399302670",
          "B": "/",
          "Token": "i-did-not-change-the-public-token-boo",
          "StunURIs": [],
          "TurnURIs": [
            "turn:myturnserver:443?transport=udp",
            "turn:myturnserver:443?transport=tcp"
          ],
          "Tokens": false,
          "Version": "0.17.5",
          "UsersEnabled": true,
          "UsersAllowRegistration": true,
          "UsersMode": "certificate",
          "Plugin": ""
        }


  /api/v1/tokens

    The tokens end point is to validate client side access tokens.

    POST application/x-www-form-urlencoded
      a: Authentication token as entered by the user (string)
      Response 200:
        {
          "success": true,
          "token": "validated-auth-token"
        }
      Response 403, 413:
        {
          "success": false,
          "code": "error-code",
          "message": "error-message"
        }


  /api/v1/rooms

    The rooms end point can be used to generate new random room ids.

    POST application/x-www-form-urlencoded
      No parameters.
      Response 200:
        {
          "success": true,
          "name": "room-name",
          "url": "https://yourserver/room-name"
        }


  /api/v1/sessions

    The sessions end point is for session interaction like authorization.

    /api/v1/sessions/{id}/

      A session id is passed in as subpath. Make sure to add the trailing
      slash (/).

      PATCH application/json
        {
          id: "session-id",
          sid: "secure-session-id",
          useridcombo: "authorization-id",
          secret: "secret-for-this-user-id"
        }
        Response 200:
          {
            "success": true,
            "userid": "user-id-for-nonce",
            "nonce": "authorization-nonce"
          }
        Response 403:
          {
            "success": false,
            "code": "error-code",
            "message": "error-message"
          }
        Response 404 text/plain:
          Returned when users are disabled on the server.


  /api/v1/users

    The users end point is for user interaction like registration.

    POST application/json
      {
        id: "session-id",
        sid: "secure-session-id"
      }
      Response 200:
        {
          "success": true,
          "userid": "user-id",
          "useridcombo": "authorization-id",
          "timestamp": 1430688014,
          "secret": "authorization-secret-for-authorization-id",
          "nonce": "authorization-nonce"
        }
      Response 400, 403:
        {
          "success": false,
          "code": "error-code",
          "message": "error-message"
        }
      Response 404 text/plain:
        Returned when user registration is disabled on the server.


  /api/v1/stats

    The stats end point provides server statistics. It is only available when
    the server configuration has it enabled.

    GET application/x-www-form-urlencoded
      details: If 1 when the stats document contains details per connection.
      Response 200:
        {
          Runtime: { /* Runtime stats (memory and such ..) */ },
          Hub: { /* Server stats */ }
        }
        Please see the implementation on exact fields of Runtime and Hub stats.


  /static/img/buddy/{flags}/{imageid}/{idx:.*}

    This endpoint provides application with user icons

    GET application/x-www-form-urlencoded
      details:
        flags: at the moment the only known flag is s{icon_size_in_pixels},
               the icons are always squares so only one dimension is needed
               example: s46
        imageid and idx: image id received via channeling API (please refer to channeling API for details)
      example: https://example.com/static/img/buddy/s46/8nG33oDk8Yv8fvK6IphL/6vjI2NLigcET/picture.jpg
      Response 200: image




End of REST API.

For latest version of Spreed WebRTC check
https://github.com/strukturag/spreed-webrtc

For questions, contact mailto:opensource@struktur.de.


(c)2016 struktur AG