Here the changes of Rest API from VMS version to version are documented, which can potentially break compatibility. In particular, functions and params can be renamed, though often deprecated names are supported for a while, when noted below.


VMS 4.1 relative to 4.0

Breaking compatibility

In function GET /media, added the signature parameter which adds a signature to the exported multimedia data. Previously, the signature had been added unconditionally, but now it is not added if the new parameter is not specified.

In function GET /ec2/analyticsLookupObjectTracks, parameter maxObjectTrackSize changed to needFullTrack. Previously this parameter was used to limit the number of object track metadata items (each item is related to a video frame). The new parameter is just a flag showing whether to select all of them or not.

In function POST /ec2/deviceAnalyticsSettings parameters deviceId and analyticsEngineId have to be passed not as URL query parameters but as keys of a JSON request in the request body. Optional parameter analyzedStreamIndex has been added to the JSON request. Parameter settings of the JSON request has been renamed to settingsValues. Request now must contain the settingsModelId field, value of which may be retrieved via the corresponding GET request. Parameters values and model of the JSON response have been renamed to settingsValues and settingsModel respectively. Parameters analyzedStreamIndex, settingsErrors and settingsModelId have been added to the JSON response.

In function GET /ec2/deviceAnalyticsSettings parameters values and model of the JSON response have been renamed to settingsValues and settingsModel respectively. Parameters analyzedStreamIndex and settingsModelId have been added to the JSON response.

In function GET /ec2/analyticsEngineSettings parameters values and model of the JSON response have been renamed to settingsValues and settingsModel respectively. Parameter settingsErrors has been added to the JSON response.

Function POST /ec2/analyticsEngineSettings expects in its body a JSON object with the following fields: settingsValues (previously this was the root object of the request), analyticsEngineId (previously was passed as a URL parameter). The URL parameter analyticsEngineId is deprectated.

Response of the function GET /ec2/analyticsEngineSettings now contains the following fields settingsValues, settingsModel, settingsErrors, and settingsModelId

In function /ec2/cameraThumbnail the sameAsAnalytics option has been removed from possible values of the streamSelectionMode URL parameter. forcedPrimary and forcedSecondary values have to be used for retrieving thumbnails of Objects detected by Analytics Plugins. Information about the stream that has been used by analytics to detect a particular Object is contained in the metadata that comes in the RTSP stream and in the response of /ec2/analyticsLookupObjectTracks as a value of the bestShot.streamIndex field. The index of the stream that is currently used by a particular Engine on a particular Device can be retrieved via the /ec2/deviceAnalyticsSettings request.

Retaining compatibility until expired

Function /api/pluginInfo is deprecated in favor of the new System-wide function /ec2/pluginInfo.


VMS 4.0 relative to 3.2

Breaking compatibility

In case of InvalidParameter or MissingParameter error, the status code has been changed from 200 OK to 422 Unprocessable Entity; in case of timeout, the status code has been changed from 200 OK to 408 Request Timeout in functions:

    /api/getCameraParam
    /api/setCameraParam

Output parameter value list can contain not only parameters specified by the user, but also additional parameter values affected by the set operation in the function:

    /api/setCameraParam

Params scheduleTask.beforeThreshold and scheduleTask.afterThreshold were removed in favor of the new recordBeforeMotionSec and recordAfterMotionSec params in functions:

    /ec2/saveCameraUserAttributesList
    /ec2/saveCameraUserAttributes
    /ec2/getCameraUserAttributesList
    /ec2/getCamerasEx

Added optional param currentPassword, which is required if new password is provided in functions:

    /api/configure
    /api/detachFromCloud

Added required param currentPassword in function /api/restoreState.

Expanded dewarpingParams and contrastParams fields in the layout items description in functions:

    /ec2/getLayouts
    /ec2/saveLayout
    /ec2/saveLayouts

Parameters layout.horizontalSpacing and layout.verticalSpacing were removed in favor of the new cellSpacing parameter in functions:

    /ec2/getLayouts
    /ec2/saveLayout
    /ec2/saveLayouts

Retaining compatibility until expired

Function /api/gettime deprecated in favor of the new function /api/getTime (deprecated function support expires after 4.0).
Result structure of the new function differs from the old one:

    timeZoneOffset - is now in milliseconds instead of seconds
    timezoneId -> timeZoneId
    utcTime -> vmsTime
    osTime - new parameter, see documentation for details

Made GET method deprecated in favor of the newly implemented POST in function /api/setCameraParam (deprecated function support expires after 4.0).
NOTE: In API documentation, this function was previously incorrectly stated as POST, but now this statement becomes true.

Made GET method deprecated in favor of the newly implemented POST in function /api/restart (deprecated function support expires after 4.0).

Retaining compatibility

Removed param scheduleTask.recordAudio (was not used) in functions:

    /ec2/saveCameraUserAttributesList
    /ec2/saveCameraUserAttributes
    /ec2/getCameraUserAttributesList
    /ec2/getCamerasEx


VMS 3.2 relative to 3.1

Breaking compatibility

Deleted deprecated function /api/image.

Retaining compatibility until expired

Made GET method deprecated in favor of POST in function /api/detachFromCloud (deprecated function support expires after 3.2).

Renamed certain param values in function /ec2/cameraThumbnail (deprecated values support expires after 3.2):

    Param imageFormat values:
        jpeg -> jpg
        tiff -> tif

    Param roundMethod values:
        exact -> precise

Errata fixed in the API documentation (not changing API behavior)

Fixed param and value names in function /ec2/cameraThumbnail:

    Param imageFormat values:
        PngFormat -> png
        JpgFormat -> jpg
        TiffFormat -> tif
        RawFormat -> raw

    Param function -> roundMethod values:
        KeyFrameBeforeMethod -> before
        PreciseMethod -> precise
        KeyFrameAfterMethod -> after

Fixed function URL prefix: /api/execAction -> /ec2/execAction.


VMS 3.1 relative to 3.0

Retaining compatibility until expired

Changed GET -> POST in function /api/mergeSystems (deprecated function support expires after 3.2). Check changed params in the API documentation.


VMS 3.0 relative to 2.6

Breaking compatibility

Renamed functions:

    /ec2/getServerUserAttributes -> /ec2/getMediaServerUserAttributesList
    /ec2/saveServerUserAttributes -> /ec2/saveMediaServerUserAttributes
    /ec2/saveServerUserAttributesList -> /ec2/saveMediaServerUserAttributesList
    /ec2/getCameraUserAttributes -> /ec2/getCameraUserAttributesList
    /api/businessEvents -> /api/getEvents
    /ec2/getBusinessRules -> /ec2/getEventRules

Changed reply format XML -> JSON in functions:

    /api/manualCamera/search
    /api/manualCamera/status
    /api/manualCamera/stop
    /api/statistics
    /api/storageSpace
    /api/storageStatus

Retaining compatibility until expired

Replaced function /api/image -> /ec2/cameraThumbnail (deprecated function support expires after 3.1). The new function can get thumbnails from cameras located on other servers (the old one can not).

Renamed param cameraID -> cameraId (deprecated name support expires after 3.2) in functions:

    /ec2/getCamerasEx
    /ec2/getCameraUserAttributesList
    /ec2/saveCameraUserAttributesList
    /ec2/saveCameraUserAttributes

Renamed param serverID -> serverId (deprecated name support expires after 3.2) in functions:

    /ec2/getMediaServerUserAttributesList
    /ec2/saveMediaServerUserAttributesList
    /ec2/saveMediaServerUserAttributes

Renamed param phisicalMemory -> physicalMemory (deprecated name support expires after 3.2) in functions:

    /ec2/saveClientInfo
    /ec2/getClientInfoList

Renamed param preferedServerId -> preferredServerId (deprecated name support expires after 3.2) in functions:

    /ec2/saveCameraUserAttributesList
    /ec2/saveCameraUserAttributes
    /ec2/getCameraUserAttributesList
    /ec2/getCamerasEx

Renamed param res_id -> cameraId (deprecated name support expires after 3.2) in functions:

    /api/doCameraDiagnosticsStep
    /api/setCameraParam
    /api/getCameraParam

Renamed param resourceId -> cameraId (deprecated name support expires after 3.2) in functions:

    /api/ptz

Renamed and merged together params mac + physicalId -> cameraId in function /ec2/bookmarks (deprecated names support expires after 3.2).

Renamed param physicalId -> cameraId (deprecated name support expires after 3.2) in functions:

    /api/image
    /api/getEvents
    /ec2/recordedTimePeriods

Changed GET -> POST in function /api/manualCamera/add (deprecated function support expires after 3.2). Check changed params in the API documentation.

Renamed param timeSinseEpochMs -> timeSinceEpochMs in function /ec2/getTimeOfServers.

Remove global setting synchronizeTimeWithInternet It implicitly turned on if settings 'primaryTimeServer' is not defined and 'timeSynchronizationEnabled' is true.