Server API

Main logic

• Chunked transfer of video feed data
• Every scene command (move,rotate,etc.) will be performed by a separate get request
  • The response of those request will hint about the state of the connection:
    • 200 Success means the connection is alive and the cookie has not expired
    • 404 Not found means the cookie id was no longer valid/found on the server. A new session is required
    • 500 Internal Server Error means an error/exception occured on the server side. The body contains the error.
• The video feed will be provided by a back-channel for realtime. This connection will use chunked messages from the server. The images themselves can be chunked or they will be integrally sent.
• The requests made by the client are identified by the server based on a cookie. This cookie will expire after a period of inactivity.

Server side accepted requests

Unless otherwise stated, all requests described will be available at the /api path.

Login/Identification

• /login
  • This is used by the client to receive a new cookie from the server and to initiate the graphics on the server side. Without this cookie no other request made by the client can succeed.
  • The response given to this request will set the cookie on the browser and will be used as a realtime channel for the video feed. The data sent will be chunked in order to allow streamable video.
  • The response header will contain the dimensions of the video streams in width and height terms named X-Image-Width and X-Image-Height. These values are not changeable or updatable. The resize will be performed by the client by other means. The video area offered by the server will suffice for a decent quality image for any size of the end canvas.
  • After a period of inactivity the cookie WILL expire on the server side. As a result this persistent connection will be closed. This will also invalidate any other new requests performed by the client. The client should acquire a new cookie by calling again /login
  • Http code 200 Success means the cookie has been succesfully allocated and video fees has started.
  • Http code 409 Conflict means the server cannot produce a new cookie. In this situation the next request should be attempted after 3 seconds.
  • 404 Not Found http error code will not be returned.

Scene rendering API

• /move?direction={direction}&amount={amount}

  • direction has the following possible values:
    • 0 -> pozitive Z axis
    • 1 -> negative Z axis
    • 2 -> positive X Axis
    • 3 -> negative X Axis
    • 4 -> positive Y Axis
    • 5 -> negative Y Axis
  • amount specifies the amount of units to move on the given axis

• /rotate?direction={direction}&amount={amount}

  • direction has the following values and meanings:
    • 0 -> rotation around Y Axis aka to the left/right
    • 1 -> rotation around X Axis
  • amount A positive value means a counter clockwise rotation around the given axis. In Degrees.

• /load with body {data}

  • data is of string type and contains the description of 3D object. The format of the object should be the same as of the .obj file format. Details here
  • Http code 200 means success, the object is valid and loaded
  • Http code 422 Unprocessable failure means the data is malformed. The body will contain the error which can be shown to the user.
  • Http code 404 will be returned with the usual meaning