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


VMS 4.1 relative to 4.0

Retaining compatibility until expired

Made GET deprecated in favor of the newly implemented POST methods with the same path and parameters encoded in a JSON object body for methods that perform changes on the server side (deprecated method support expires after 4.2):

    /api/backupControl (with non-empty "action" URL param)
    /api/backupDatabase
    /api/configure
    /api/cookieLogout
    /api/createEvent
    /api/debugEvent
    /api/detachFromSystem
    /api/execute*
    /api/manualCamera/add
    /api/manualCamera/search
    /api/manualCamera/stop
    /api/mergeSystems
    /api/ptz (with "command" URL param which does not start with "Get")
    /api/rebuildArchive
    /api/settime
    /api/setupCloudSystem
    /api/setupLocalSystem
    /api/systemSettings
    /api/transmitAudio
    /ec2/bookmarks/add
    /ec2/bookmarks/delete
    /ec2/bookmarks/update
Example:
    GET /api/systemSettings?smtpTimeout=30&smtpUser=test HTTP/1.1
Replaced by:
    POST /api/systemSettings HTTP/1.1
    Content-Type: application/json
    Content-Length: 40

    {"smtpTimeout": 30, "smtpUser": "test"}
GET methods with paramiters which do not cause any server changes are still allowed:
    /api/backupControl (without or with empty "action" URL param)
    /api/ptz (with "command" URL param which starts with "Get")

The following modifying GET methods are deprecated because there is already incompatible POST version available (see their documentation for details; deprecated method support expires after 4.2):

    /api/setCameraParam

Breaking compatibility

In method 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 method 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 method 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. Parameters values and model of the JSON response have been renamed to settingsValues and settingsModel respectively. Parameter analyzedStreamIndex has been added to the JSON response.

In method GET /ec2/deviceAnalyticsSettings parameters values and model of the JSON response have been renamed to settingsValues and settingsModel respectively. Parameter analyzedStreamIndex has been added to the JSON response.

In method /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

Method /api/pluginInfo is deprecated in favor of the new System-wide method /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 methods:

    /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 method:

    /api/setCameraParam

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

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

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

    /api/configure
    /api/detachFromCloud

Added required param currentPassword in method /api/restoreState.

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

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

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

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

Retaining compatibility until expired

Method /api/gettime deprecated in favor of the new method /api/getTime (deprecated method support expires after 4.0).
Result structure of the new method 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 deprecated in favor of the newly implemented POST in method /api/setCameraParam (deprecated method support expires after 4.0).
NOTE: In API documentation, this method was previously incorrectly stated as POST, but now this statement becomes true.

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

Retaining compatibility

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

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


VMS 3.2 relative to 3.1

Breaking compatibility

Deleted deprecated method /api/image.

Retaining compatibility until expired

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

Renamed certain param values in method /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 method /ec2/cameraThumbnail:

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

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

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


VMS 3.1 relative to 3.0

Retaining compatibility until expired

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


VMS 3.0 relative to 2.6

Breaking compatibility

Renamed methods:

    /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 methods:

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

Retaining compatibility until expired

Replaced method /api/image -> /ec2/cameraThumbnail (deprecated method support expires after 3.1). The new method 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 methods:

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

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

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

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

    /ec2/saveClientInfo
    /ec2/getClientInfoList

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

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

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

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

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

    /api/ptz

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

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

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

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

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

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