Versioning REST API (#349)

* Versioning REST API

* Update doc versions

Author: starwarfan

doc/Client-Portal Protocol.md

@@ -1,4 +1,4 @@
-# Client-Portal Communication Protocol
+# Client-Portal Communication Protocol (version 1.1)
 <!--
 |date | contributor | revision |
 | :-------: | :------------: | :------------: |

doc/servermd/RESTAPI.md

@@ -542,11 +542,11 @@ Streams model:
     }
 Resources:
 
-- /v1/rooms/{roomId}/streams
-- /v1/rooms/{roomId}/streams/{streamId}
+- /v1.1/rooms/{roomId}/streams
+- /v1.1/rooms/{roomId}/streams/{streamId}
 
 ### List Streams {#RESTAPIsection5_3_1}
-**GET ${host}/v1/rooms/{roomId}/streams**
+**GET ${host}/v1.1/rooms/{roomId}/streams**
 
 Description:<br>
 List streams in the specified room.<br>
@@ -562,7 +562,7 @@ response body:
 |      json     | [ Object(StreamInfo) ] |
 
 ### Get Stream {#RESTAPIsection5_3_2}
-**GET ${host}/v1/rooms/{roomId}/streams/{streamId}**
+**GET ${host}/v1.1/rooms/{roomId}/streams/{streamId}**
 
 Description:<br>
 Get a stream's information from the specified room.<br>
@@ -578,7 +578,7 @@ response body:
 |      json     | object(StreamInfo) |
 
 ### Update Stream {#RESTAPIsection5_3_3}
-**PATCH ${host}/v1/rooms/{roomId}/streams/{streamId}**
+**PATCH ${host}/v1.1/rooms/{roomId}/streams/{streamId}**
 
 Description:<br>
 Update a stream's given attributes in the specified room.<br>
@@ -637,7 +637,7 @@ response body:
 
 
 ### Drop Stream {#RESTAPIsection5_3_4}
-**DELETE ${host}/v1/rooms/{roomId}/streams/{streamId}**
+**DELETE ${host}/v1.1/rooms/{roomId}/streams/{streamId}**
 
 Description:<br>
 Delete the specified stream from the specified room.<br>
@@ -657,11 +657,11 @@ Streaming-ins model is same as Stream model.
 
 Resources:
 
-- /v1/rooms/{roomId}/streaming-ins
-- /v1/rooms/{roomId}/streaming-ins/{streamId}
+- /v1.1/rooms/{roomId}/streaming-ins
+- /v1.1/rooms/{roomId}/streaming-ins/{streamId}
 
 ### Start Streaming-in {#RESTAPIsection5_4_1}
-**POST ${host}/v1/rooms/{roomId}/streaming-ins**
+**POST ${host}/v1.1/rooms/{roomId}/streaming-ins**
 
 Description:<br>
 Add an external RTSP/RTMP stream to the specified room.<br>
@@ -693,7 +693,7 @@ response body:
 |  json | object(StreamInfo) |
 
 ### Stop Streaming-in {#RESTAPIsection5_4_2}
-**DELETE ${host}/v1/rooms/{roomId}/streaming-ins/{streamId}**
+**DELETE ${host}/v1.1/rooms/{roomId}/streaming-ins/{streamId}**
 
 Description:<br>
 Stop the specified external streaming-in in the specified room.<br>

source/agent/conference/conference.js

@@ -1829,7 +1829,7 @@ var Conference = function (rpcClient, selfRpcId) {
           }, 60);
         });
       }).then(() => {
-        callback('callback', streams[stream_id]);
+        callback('callback', Stream.toPortalFormat(streams[stream_id]));
       }).catch((e) => {
         callback('callback', 'error', e.message ? e.message : e);
         removeStream(stream_id);
@@ -2012,7 +2012,7 @@ var Conference = function (rpcClient, selfRpcId) {
     ).then(() => {
       return Promise.all(muteReq.map((r) => {return setStreamMute(streamId, r.track, r.mute);}));
     }).then(() => {
-      callback('callback', streams[streamId]);
+      callback('callback', Stream.toPortalFormat(streams[streamId]));
     }, (err) => {
       log.warn('failed in controlStream, reason:', err.message ? err.message : err);
       callback('callback', 'error', err.message ? err.message : err);

source/management_api/api.js

@@ -48,17 +48,8 @@ var bodyParser = require('body-parser');
 var app = express();
 
 var serverAuthenticator = require('./auth/serverAuthenticator');
-var roomsResource = require('./resource/roomsResource');
-var roomResource = require('./resource/roomResource');
-var tokensResource = require('./resource/tokensResource');
 var servicesResource = require('./resource/servicesResource');
 var serviceResource = require('./resource/serviceResource');
-var participantsResource = require('./resource/participantsResource');
-var streamsResource = require('./resource/streamsResource');
-var streamingOutsResource = require('./resource/streamingOutsResource');
-var recordingsResource = require('./resource/recordingsResource');
-var sipcallsResource = require('./resource/sipcallsResource');
-var analyticsResource = require('./resource/analyticsResource');
 
 // parse application/x-www-form-urlencoded
 app.use(bodyParser.urlencoded({ extended: true }))
@@ -77,7 +68,7 @@ app.options('*', function(req, res) {
 });
 
 // Only following paths need authentication.
-var authPaths = ['/rooms*', '/v1/rooms*', '/services*', '/cluster*'];
+var authPaths = ['/v1/rooms*', '/v1.1/rooms*', '/services*', '/cluster*'];
 app.get(authPaths, serverAuthenticator.authenticate);
 app.post(authPaths, serverAuthenticator.authenticate);
 app.delete(authPaths, serverAuthenticator.authenticate);
@@ -90,64 +81,13 @@ app.get('/services', servicesResource.represent);
 app.get('/services/:service', serviceResource.represent);
 app.delete('/services/:service', serviceResource.deleteService);
 
-////////////////////////////////////////////////////////////////////////////////////////////
-// v1 interface begin
-// /////////////////////////////////////////////////////////////////////////////////////////
-
-//Room management
-app.post('/v1/rooms', roomsResource.createRoom); //FIXME: The definition of 'options' needs to be refined.
-app.get('/v1/rooms', roomsResource.represent); //FIXME: The list result needs to be simplified.
-app.get('/v1/rooms/:room', roomResource.represent); //FIXME: The detailed format of a complete room configuration data object needs to be refined.
-app.delete('/v1/rooms/:room', roomResource.deleteRoom);
-app.put('/v1/rooms/:room', roomResource.updateRoom);
-app.patch('/v1/rooms/:room', (req, res, next) => next(new e.AppError('Not implemented'))); //FIXME: To be implemented.
-
-//Room checker for all the sub-resources
-app.use('/v1/rooms/:room/*', roomResource.validate);
-
-//Participant management
-app.get('/v1/rooms/:room/participants', participantsResource.getList);
-app.get('/v1/rooms/:room/participants/:participant', participantsResource.get);
-app.patch('/v1/rooms/:room/participants/:participant', participantsResource.patch);
-app.delete('/v1/rooms/:room/participants/:participant', participantsResource.delete);
-
-//Stream(including external streaming-in) management
-app.get('/v1/rooms/:room/streams', streamsResource.getList);
-app.get('/v1/rooms/:room/streams/:stream', streamsResource.get);
-app.patch('/v1/rooms/:room/streams/:stream', streamsResource.patch);
-app.delete('/v1/rooms/:room/streams/:stream', streamsResource.delete);
-app.post('/v1/rooms/:room/streaming-ins', streamsResource.addStreamingIn);//FIXME: Validation on body.type === 'streaming' is needed.
-app.delete('/v1/rooms/:room/streaming-ins/:stream', streamsResource.delete);
-
-//External streaming-out management
-app.get('/v1/rooms/:room/streaming-outs', streamingOutsResource.getList);
-app.post('/v1/rooms/:room/streaming-outs', streamingOutsResource.add);//FIXME: Validation on body.type === 'streaming' is needed.
-app.patch('/v1/rooms/:room/streaming-outs/:id', streamingOutsResource.patch);
-app.delete('/v1/rooms/:room/streaming-outs/:id', streamingOutsResource.delete);
-
-//Server side recording management
-app.get('/v1/rooms/:room/recordings', recordingsResource.getList);
-app.post('/v1/rooms/:room/recordings', recordingsResource.add);//FIXME: Validation on body.type === 'recording' is needed.
-app.patch('/v1/rooms/:room/recordings/:id', recordingsResource.patch);
-app.delete('/v1/rooms/:room/recordings/:id', recordingsResource.delete);
-
-//Sip call management
-app.get('/v1/rooms/:room/sipcalls', sipcallsResource.getList);
-app.post('/v1/rooms/:room/sipcalls', sipcallsResource.add);
-app.patch('/v1/rooms/:room/sipcalls/:id', sipcallsResource.patch);
-app.delete('/v1/rooms/:room/sipcalls/:id', sipcallsResource.delete);
-
-//Analytic management
-app.get('/v1/rooms/:room/analytics', analyticsResource.getList);
-app.post('/v1/rooms/:room/analytics', analyticsResource.add);
-app.delete('/v1/rooms/:room/analytics/:id', analyticsResource.delete);
-
-//Create token.
-app.post('/v1/rooms/:room/tokens', tokensResource.create);
-
-////////////////////////////////////////////////////////////////////////////////////////////
-// v1 interface end
-// /////////////////////////////////////////////////////////////////////////////////////////
+// API for version 1.0.
+var routerV1 = require('./resource/v1');
+app.use('/v1', routerV1);
+
+// API for version 1.1.
+var routerV1_1 = require('./resource/v1.1');
+app.use('/v1.1', routerV1_1);
 
 // for path not match
 app.use('*', function(req, res, next) {

source/management_api/resource/v1.1/index.js

@@ -0,0 +1,20 @@
+// Copyright (C) <2019> Intel Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * Router for v1.1 interfaces
+ */
+'use strict';
+var express = require('express')
+var router = express.Router()
+var streamsResource = require('./streamsResource');
+
+//Stream(including external streaming-in) management
+router.get('/rooms/:room/streams', streamsResource.getList);
+router.get('/rooms/:room/streams/:stream', streamsResource.get);
+router.patch('/rooms/:room/streams/:stream', streamsResource.patch);
+router.delete('/rooms/:room/streams/:stream', streamsResource.delete);
+router.post('/rooms/:room/streaming-ins', streamsResource.addStreamingIn);//FIXME: Validation on body.type === 'streaming' is needed.
+router.delete('/rooms/:room/streaming-ins/:stream', streamsResource.delete);
+
+module.exports = router

source/management_api/resource/streamsResource.js renamed to source/management_api/resource/v1.1/streamsResource.js

@@ -3,11 +3,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 'use strict';
-var dataAccess = require('../data_access');
-var requestHandler = require('../requestHandler');
-var e = require('../errors');
+var dataAccess = require('../../data_access');
+var requestHandler = require('../../requestHandler');
+var e = require('../../errors');
 
-var logger = require('./../logger').logger;
+var logger = require('../../logger').logger;
 
 // Logger
 var log = logger.getLogger('StreamsResource');

source/management_api/resource/analyticsResource.js renamed to source/management_api/resource/v1/analyticsResource.js

@@ -3,10 +3,10 @@
 // SPDX-License-Identifier: Apache-2.0
 
 'use strict';
-var requestHandler = require('../requestHandler');
-var e = require('../errors');
+var requestHandler = require('../../requestHandler');
+var e = require('../../errors');
 
-var logger = require('./../logger').logger;
+var logger = require('./../../logger').logger;
 
 // Logger
 var log = logger.getLogger('AnalyticsResource');

source/management_api/resource/v1/index.js

@@ -0,0 +1,72 @@
+// Copyright (C) <2019> Intel Corporation
+//
+// SPDX-License-Identifier: Apache-2.0
+/*
+ * Router for v1 interfaces
+ */
+'use strict';
+var express = require('express')
+var router = express.Router()
+
+var roomsResource = require('./roomsResource');
+var roomResource = require('./roomResource');
+var tokensResource = require('./tokensResource');
+var participantsResource = require('./participantsResource');
+var streamsResource = require('./streamsResource');
+var streamingOutsResource = require('./streamingOutsResource');
+var recordingsResource = require('./recordingsResource');
+var sipcallsResource = require('./sipcallsResource');
+var analyticsResource = require('./analyticsResource');
+
+//Room management
+router.post('/rooms', roomsResource.createRoom); //FIXME: The definition of 'options' needs to be refined.
+router.get('/rooms', roomsResource.represent); //FIXME: The list result needs to be simplified.
+router.get('/rooms/:room', roomResource.represent); //FIXME: The detailed format of a complete room configuration data object needs to be refined.
+router.delete('/rooms/:room', roomResource.deleteRoom);
+router.put('/rooms/:room', roomResource.updateRoom);
+router.patch('/rooms/:room', (req, res, next) => next(new e.routerError('Not implemented'))); //FIXME: To be implemented.
+
+//Room checker for all the sub-resources
+router.use('/rooms/:room/*', roomResource.validate);
+
+//Participant management
+router.get('/rooms/:room/participants', participantsResource.getList);
+router.get('/rooms/:room/participants/:participant', participantsResource.get);
+router.patch('/rooms/:room/participants/:participant', participantsResource.patch);
+router.delete('/rooms/:room/participants/:participant', participantsResource.delete);
+
+//Stream(including external streaming-in) management
+router.get('/rooms/:room/streams', streamsResource.getList);
+router.get('/rooms/:room/streams/:stream', streamsResource.get);
+router.patch('/rooms/:room/streams/:stream', streamsResource.patch);
+router.delete('/rooms/:room/streams/:stream', streamsResource.delete);
+router.post('/rooms/:room/streaming-ins', streamsResource.addStreamingIn);//FIXME: Validation on body.type === 'streaming' is needed.
+router.delete('/rooms/:room/streaming-ins/:stream', streamsResource.delete);
+
+//External streaming-out management
+router.get('/rooms/:room/streaming-outs', streamingOutsResource.getList);
+router.post('/rooms/:room/streaming-outs', streamingOutsResource.add);//FIXME: Validation on body.type === 'streaming' is needed.
+router.patch('/rooms/:room/streaming-outs/:id', streamingOutsResource.patch);
+router.delete('/rooms/:room/streaming-outs/:id', streamingOutsResource.delete);
+
+//Server side recording management
+router.get('/rooms/:room/recordings', recordingsResource.getList);
+router.post('/rooms/:room/recordings', recordingsResource.add);//FIXME: Validation on body.type === 'recording' is needed.
+router.patch('/rooms/:room/recordings/:id', recordingsResource.patch);
+router.delete('/rooms/:room/recordings/:id', recordingsResource.delete);
+
+//Sip call management
+router.get('/rooms/:room/sipcalls', sipcallsResource.getList);
+router.post('/rooms/:room/sipcalls', sipcallsResource.add);
+router.patch('/rooms/:room/sipcalls/:id', sipcallsResource.patch);
+router.delete('/rooms/:room/sipcalls/:id', sipcallsResource.delete);
+
+//Analytic management
+router.get('/rooms/:room/analytics', analyticsResource.getList);
+router.post('/rooms/:room/analytics', analyticsResource.add);
+router.delete('/rooms/:room/analytics/:id', analyticsResource.delete);
+
+//Create token.
+router.post('/rooms/:room/tokens', tokensResource.create);
+
+module.exports = router

source/management_api/resource/participantsResource.js renamed to source/management_api/resource/v1/participantsResource.js

@@ -3,11 +3,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 'use strict';
-var dataAccess = require('../data_access');
-var requestHandler = require('../requestHandler');
-var e = require('../errors');
+var dataAccess = require('../../data_access');
+var requestHandler = require('../../requestHandler');
+var e = require('../../errors');
 
-var logger = require('./../logger').logger;
+var logger = require('./../../logger').logger;
 
 // Logger
 var log = logger.getLogger('ParticipantsResource');

source/management_api/resource/recordingsResource.js renamed to source/management_api/resource/v1/recordingsResource.js

@@ -3,11 +3,11 @@
 // SPDX-License-Identifier: Apache-2.0
 
 'use strict';
-var dataAccess = require('../data_access');
-var requestHandler = require('../requestHandler');
-var e = require('../errors');
+var dataAccess = require('../../data_access');
+var requestHandler = require('../../requestHandler');
+var e = require('../../errors');
 
-var logger = require('./../logger').logger;
+var logger = require('./../../logger').logger;
 
 // Logger
 var log = logger.getLogger('RecordingsResource');