From 11bd2139f4b15558ffa6337d825030779a88c254 Mon Sep 17 00:00:00 2001 From: pliablepixels Date: Sat, 13 Jun 2015 16:30:28 +0000 Subject: [PATCH 1/6] Added API version in addition to ZM version --- CMakeLists.txt | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CMakeLists.txt b/CMakeLists.txt index e74f3b13a..2895b9257 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -5,6 +5,8 @@ cmake_minimum_required (VERSION 2.6) project (zoneminder) set(zoneminder_VERSION "1.28.1") +# make API version a minor of ZM version +set(zoneminder_API_VERSION "${zoneminder_VERSION}.1") # CMake does not allow out-of-source build if CMakeCache.exists # in the source folder. Abort and notify the user @@ -627,6 +629,7 @@ endif(NOT POLKIT_FOUND) set(ZM_PID "${ZM_RUNDIR}/zm.pid") set(ZM_CONFIG "${ZM_CONFIG_DIR}/zm.conf") set(VERSION "${zoneminder_VERSION}") +set(API_VERSION "${zoneminder_API_VERSION}") set(PKGDATADIR "${CMAKE_INSTALL_PREFIX}/${CMAKE_INSTALL_DATADIR}/zoneminder") set(BINDIR "${CMAKE_INSTALL_FULL_BINDIR}") set(LIBDIR "${CMAKE_INSTALL_FULL_LIBDIR}") From 12ba217de0ad812c46e25ffef0ad253fc2211dcf Mon Sep 17 00:00:00 2001 From: pliablepixels Date: Sat, 13 Jun 2015 16:32:37 +0000 Subject: [PATCH 2/6] Added API version in addition to ZM version, also added loadConfig code that was there in the angular-ui branch but not merged to master --- web/api/app/Config/bootstrap.php.in | 34 +++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/web/api/app/Config/bootstrap.php.in b/web/api/app/Config/bootstrap.php.in index e4102d62b..cff9a29dd 100644 --- a/web/api/app/Config/bootstrap.php.in +++ b/web/api/app/Config/bootstrap.php.in @@ -107,3 +107,37 @@ CakeLog::config('error', array( 'types' => array('warning', 'error', 'critical', 'alert', 'emergency'), 'file' => 'error', )); + +Configure::write('ZM_CONFIG', '@ZM_CONFIG@'); +Configure::write('ZM_VERSION', '@VERSION@'); +Configure::write('ZM_API_VERSION', '@API_VERSION@'); + +loadConfigFile(); + +function loadConfigFile() { + $configFile = Configure::read('ZM_CONFIG'); + $localConfigFile = basename($configFile); + if ( file_exists( $localConfigFile ) && filesize( $localConfigFile ) > 0 ) + { + if ( php_sapi_name() == 'cli' && empty($_SERVER['REMOTE_ADDR']) ) + print( "Warning, overriding installed $localConfigFile file with local copy\n" ); + else + error_log( "Warning, overriding installed $localConfigFile file with local copy" ); + $configFile = $localConfigFile; + } + + $cfg = fopen( $configFile, "r") or die("Could not open config file."); + while ( !feof($cfg) ) + { + $str = fgets( $cfg, 256 ); + if ( preg_match( '/^\s*$/', $str )) + continue; + elseif ( preg_match( '/^\s*#/', $str )) + continue; + elseif ( preg_match( '/^\s*([^=\s]+)\s*=\s*(.*?)\s*$/', $str, $matches )) + Configure::write("$matches[1]", "$matches[2]"); + } + fclose( $cfg ); +} + + From 7112001b64672c826cad1b4686e136c62d5cba3a Mon Sep 17 00:00:00 2001 From: pliablepixels Date: Sat, 13 Jun 2015 16:33:15 +0000 Subject: [PATCH 3/6] getVersion.json now returns both ZM version and API version --- web/api/app/Controller/HostController.php | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/web/api/app/Controller/HostController.php b/web/api/app/Controller/HostController.php index 973caf286..ee5ecd30f 100644 --- a/web/api/app/Controller/HostController.php +++ b/web/api/app/Controller/HostController.php @@ -101,10 +101,12 @@ class HostController extends AppController { function getVersion() { $version = Configure::read('ZM_VERSION'); + $apiversion = Configure::read('ZM_API_VERSION'); $this->set(array( 'version' => $version, - '_serialize' => array('version') + 'apiversion' => $apiversion, + '_serialize' => array('version', 'apiversion') )); } } From 22ec67dd3f7e28f1ab01dc8ec0c1c95c083c0e59 Mon Sep 17 00:00:00 2001 From: SteveGilvarry Date: Sun, 24 May 2015 23:39:44 +1000 Subject: [PATCH 4/6] Find avconv as alternative to ffmpeg --- CMakeLists.txt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index e74f3b13a..fb1a07f59 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -452,7 +452,9 @@ if(NOT ZM_NO_FFMPEG) endif(SWSCALE_LIBRARIES) # Find the path to the ffmpeg executable - find_program(FFMPEG_EXECUTABLE ffmpeg PATH_SUFFIXES ffmpeg) + find_program(FFMPEG_EXECUTABLE + NAMES ffmpeg avconv + PATH_SUFFIXES ffmpeg) if(FFMPEG_EXECUTABLE) set(PATH_FFMPEG "${FFMPEG_EXECUTABLE}") set(OPT_FFMPEG "yes") From 3ef916f49c1bffc743c26bed5fd7f89857124c44 Mon Sep 17 00:00:00 2001 From: Pliable Pixels Date: Sun, 14 Jun 2015 10:51:28 -0400 Subject: [PATCH 5/6] Update api.rst --- docs/api.rst | 169 ++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 139 insertions(+), 30 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 26b6be251..1217a44ea 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -1,10 +1,10 @@ API -=== +^^^ -This document will provide an overview of ZoneMinder's API. +This document will provide an overview of ZoneMinder's API. This is work in progress. Overview --------- +^^^^^^^^ In an effort to further 'open up' ZoneMinder, an API was needed. This will allow quick integration with and development of ZoneMinder. @@ -14,7 +14,7 @@ provides a RESTful service and supports CRUD (create, retrieve, update, delete) functions for Monitors, Events, Frames, Zones and Config. Examples --------- +^^^^^^^^ Here be a list of examples. Some results may be truncated. @@ -22,80 +22,177 @@ You will see each URL ending in either ``.xml`` or ``.json``. This is the format of the request, and it determines the format that any data returned to you will be in. I like json, however you can use xml if you'd like. +(In all examples, replace 'server' with IP or hostname & port where ZoneMinder is running) + Return a list of all monitors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``curl -XGET http://zmdevapi/monitors.json`` +:: + curl -XGET http://server/zm/api/monitors.json Retrieve monitor 1 -^^^^^^^^^^^^^^^^^^ -``curl -XGET http://zmdevapi/monitors/1.json`` +^^^^^^^^^^^^^^^^^^^ + +:: + curl -XGET http://server/zm/api/monitors/1.json + + +Change State of Monitor 1 +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This API changes monitor 1 to Modect and Enabled +``` +curl -XPOST http://server/zm/api/monitors/1.json -d "Monitor[Function]=Modect&Monitor[Enabled]:true" +``` Add a monitor -^^^^^^^^^^^^^ +^^^^^^^^^^^^^^ This command will add a new http monitor. -``curl -XPOST http://zmdevapi/monitors.js -d "Monitor[Name]=Cliff-Burton \ +``` +curl -XPOST http://server/zm/api/monitors.json -d "Monitor[Name]=Cliff-Burton \ &Monitor[Function]=Modect \ &Monitor[Protocol]=http \ &Monitor[Method]=simple \ -&Monitor[Host]=ussr:pass@192.168.11.20 \ +&Monitor[Host]=usr:pass@192.168.11.20 \ &Monitor[Port]=80 \ &Monitor[Path]=/mjpg/video.mjpg \ &Monitor[Width]=704 \ &Monitor[Height]=480 \ -&Monitor[Colours]=4"`` +&Monitor[Colours]=4" +``` Edit monitor 1 -^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^ This command will change the 'Name' field of Monitor 1 to 'test1' -``curl -XPUT http://zmdevapi/monitors/1.json -d "Monitor[Name]=test1"`` +``` +curl -XPUT http://server/zm/api/monitors/1.json -d "Monitor[Name]=test1" +``` Delete monitor 1 -^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^ This command will delete Monitor 1, but will _not_ delete any Events which depend on it. - -``curl -XDELETE http://zmdevapi/monitors/1.json`` +``` +curl -XDELETE http://server/zm/api/monitors/1.json +``` Return a list of all events -^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``curl -XGET http://zmdevapi/events.json`` +``` +curl -XGET http://server/zm/api/events.json +``` -Retrieve event 1 -^^^^^^^^^^^^^^^^ -``curl -XGET http://zmdevapi/events/1.json`` +Note that events list can be quite large and this API (as with all other APIs in ZM) +uses pagination. Each page returns a specific set of entries. By default this is 25 +and ties into WEB_EVENTS_PER_PAGE in the ZM options menu. + +So the logic to iterate through all events should be something like this (pseudocode): +(unfortunately there is no way to get pageCount without getting the first page) +``` +data = http://server/zm/api/events.json?page=1 # this returns the first page +# The json object returned now has a property called data.pagination.pageCount +count = data.pagination.pageCount; +for (i=1, i=:2015-05-15 18:43:56/EndTime <=:2015-05-16 18:43:56.json +``` + +To try this in CuRL, you need to URL escape the spaces like so: + +``` +curl -XGET "http://server/zm/api/events/index/MonitorId:5/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:2015-05-16%2018:43:56.json" +``` + +Return a list of events for all monitors within a specified date/time range +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +``` +curl -XGET "http://server/zm/api/events/index/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:208:43:56.json" +``` + + +Configuration Apis +^^^^^^^^^^^^^^^^^^^ + +The APIs allow you to access all the configuration parameters of ZM that you typically set inside the web console. +This returns the full list of configuration parameters: + +``` +curl -XGET http://server/zm/api/configs.json +``` + +Each configuration parameter has an Id, Name, Value and other fields. Chances are you are likely only going to focus on these 3. + +(Example of changing config TBD) + +Run State Apis ^^^^^^^^^^^^^^^ -This command will change the 'Value' field of Config 121 to 901. +ZM API can be used to start/stop/restart/list states of ZM as well +Examples: + +``` +curl -XGET http://server/zm/api/states.json # returns list of run states +curl -XPOST http://server/zm/api/states/change/restart.json #restarts ZM +curl -XPOST http://server/zm/api/states/change/stop.json #Stops ZM +curl -XPOST http://server/zm/api/states/change/start.json #Starts ZM +``` -``curl -XPUT http://zmdevapi/configs/121.json -d "Config[Value]=901"`` Create a Zone -^^^^^^^^^^^^^ +^^^^^^^^^^^^^^ -``curl -XPOST http://zmdevapi/zones.json -d "Zone[Name]=Jason-Newsted \ +``` +curl -XPOST http://server/zm/api/zones.json -d "Zone[Name]=Jason-Newsted \ &Zone[MonitorId]=3 \ &Zone[Type]=Active \ &Zone[Units]=Percent \ @@ -115,4 +212,16 @@ Create a Zone &Zone[MaxBlobPixels]= \ &Zone[MinBlobs]=1 \ &Zone[MaxBlobs]= \ -&Zone[OverloadFrames]=0"`` +&Zone[OverloadFrames]=0" +``` + +Host APIs +^^^^^^^^^^ + +ZM APIs have various APIs that help you in determining host (aka ZM) daemon status, load etc. Some examples: + +``` +curl -XGET http://server/zm/api/host/daemonCheck.json # 1 = ZM running 0=not running +curl -XGET http://server/zm/api/host/getLoad.json # returns current load of ZM +curl -XGET http://server/zm/api/host/getDiskPercent.json # returns in GB (not percentage), disk usage per monitor (that is, space taken to store various event related information,images etc. per monitor) `` +``` From 71665a331568faefa437c3b8c080d7074273a3e9 Mon Sep 17 00:00:00 2001 From: Pliable Pixels Date: Sun, 14 Jun 2015 11:21:00 -0400 Subject: [PATCH 6/6] Added updated API information Reflected new APIs, corrected and updated examples --- docs/api.rst | 224 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 131 insertions(+), 93 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 1217a44ea..c5baaafb8 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -24,16 +24,25 @@ you will be in. I like json, however you can use xml if you'd like. (In all examples, replace 'server' with IP or hostname & port where ZoneMinder is running) +API Version +^^^^^^^^^^^ +To retrieve the API version: +:: + http://server/zm/api/host/getVersion.json + + Return a list of all monitors ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ :: + curl -XGET http://server/zm/api/monitors.json Retrieve monitor 1 ^^^^^^^^^^^^^^^^^^^ -:: + :: + curl -XGET http://server/zm/api/monitors/1.json @@ -41,36 +50,37 @@ Change State of Monitor 1 ^^^^^^^^^^^^^^^^^^^^^^^^^^ This API changes monitor 1 to Modect and Enabled -``` -curl -XPOST http://server/zm/api/monitors/1.json -d "Monitor[Function]=Modect&Monitor[Enabled]:true" -``` +:: + + curl -XPOST http://server/zm/api/monitors/1.json -d "Monitor[Function]=Modect&Monitor[Enabled]:true" Add a monitor ^^^^^^^^^^^^^^ This command will add a new http monitor. -``` -curl -XPOST http://server/zm/api/monitors.json -d "Monitor[Name]=Cliff-Burton \ -&Monitor[Function]=Modect \ -&Monitor[Protocol]=http \ -&Monitor[Method]=simple \ -&Monitor[Host]=usr:pass@192.168.11.20 \ -&Monitor[Port]=80 \ -&Monitor[Path]=/mjpg/video.mjpg \ -&Monitor[Width]=704 \ -&Monitor[Height]=480 \ -&Monitor[Colours]=4" -``` +:: + + curl -XPOST http://server/zm/api/monitors.json -d "Monitor[Name]=Cliff-Burton \ + &Monitor[Function]=Modect \ + &Monitor[Protocol]=http \ + &Monitor[Method]=simple \ + &Monitor[Host]=usr:pass@192.168.11.20 \ + &Monitor[Port]=80 \ + &Monitor[Path]=/mjpg/video.mjpg \ + &Monitor[Width]=704 \ + &Monitor[Height]=480 \ + &Monitor[Colours]=4" Edit monitor 1 ^^^^^^^^^^^^^^^ This command will change the 'Name' field of Monitor 1 to 'test1' -``` -curl -XPUT http://server/zm/api/monitors/1.json -d "Monitor[Name]=test1" -``` +:: + + curl -XPUT http://server/zm/api/monitors/1.json -d "Monitor[Name]=test1" + Delete monitor 1 ^^^^^^^^^^^^^^^^^ @@ -78,16 +88,18 @@ Delete monitor 1 This command will delete Monitor 1, but will _not_ delete any Events which depend on it. -``` -curl -XDELETE http://server/zm/api/monitors/1.json -``` +:: + + curl -XDELETE http://server/zm/api/monitors/1.json + Return a list of all events ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``` -curl -XGET http://server/zm/api/events.json -``` +:: + + curl -XGET http://server/zm/api/events.json + Note that events list can be quite large and this API (as with all other APIs in ZM) uses pagination. Each page returns a specific set of entries. By default this is 25 @@ -95,46 +107,51 @@ and ties into WEB_EVENTS_PER_PAGE in the ZM options menu. So the logic to iterate through all events should be something like this (pseudocode): (unfortunately there is no way to get pageCount without getting the first page) -``` -data = http://server/zm/api/events.json?page=1 # this returns the first page -# The json object returned now has a property called data.pagination.pageCount -count = data.pagination.pageCount; -for (i=1, i=:2015-05-15 18:43:56/EndTime <=:2015-05-16 18:43:56.json -``` +:: + + http://server/zm/api/events/events/index/MonitorId:5/StartTime >=:2015-05-15 18:43:56/EndTime <=:2015-05-16 18:43:56.json + To try this in CuRL, you need to URL escape the spaces like so: -``` -curl -XGET "http://server/zm/api/events/index/MonitorId:5/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:2015-05-16%2018:43:56.json" -``` +:: + + curl -XGET "http://server/zm/api/events/index/MonitorId:5/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:2015-05-16%2018:43:56.json" + Return a list of events for all monitors within a specified date/time range ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``` -curl -XGET "http://server/zm/api/events/index/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:208:43:56.json" -``` +:: + + curl -XGET "http://server/zm/api/events/index/StartTime%20>=:2015-05-15%2018:43:56/EndTime%20<=:208:43:56.json" + Configuration Apis @@ -166,9 +186,10 @@ Configuration Apis The APIs allow you to access all the configuration parameters of ZM that you typically set inside the web console. This returns the full list of configuration parameters: -``` -curl -XGET http://server/zm/api/configs.json -``` +:: + + curl -XGET http://server/zm/api/configs.json + Each configuration parameter has an Id, Name, Value and other fields. Chances are you are likely only going to focus on these 3. @@ -180,48 +201,65 @@ Run State Apis ZM API can be used to start/stop/restart/list states of ZM as well Examples: -``` -curl -XGET http://server/zm/api/states.json # returns list of run states -curl -XPOST http://server/zm/api/states/change/restart.json #restarts ZM -curl -XPOST http://server/zm/api/states/change/stop.json #Stops ZM -curl -XPOST http://server/zm/api/states/change/start.json #Starts ZM -``` +:: + + curl -XGET http://server/zm/api/states.json # returns list of run states + curl -XPOST http://server/zm/api/states/change/restart.json #restarts ZM + curl -XPOST http://server/zm/api/states/change/stop.json #Stops ZM + curl -XPOST http://server/zm/api/states/change/start.json #Starts ZM + Create a Zone ^^^^^^^^^^^^^^ -``` -curl -XPOST http://server/zm/api/zones.json -d "Zone[Name]=Jason-Newsted \ -&Zone[MonitorId]=3 \ -&Zone[Type]=Active \ -&Zone[Units]=Percent \ -&Zone[NumCoords]=4 \ -&Zone[Coords]=0,0 639,0 639,479 0,479 \ -&Zone[AlarmRGB]=16711680 \ -&Zone[CheckMethod]=Blobs \ -&Zone[MinPixelThreshold]=25 \ -&Zone[MaxPixelThreshold]= \ -&Zone[MinAlarmPixels]=9216 \ -&Zone[MaxAlarmPixels]= \ -&Zone[FilterX]=3 \ -&Zone[FilterY]=3 \ -&Zone[MinFilterPixels]=9216 \ -&Zone[MaxFilterPixels]=230400 \ -&Zone[MinBlobPixels]=6144 \ -&Zone[MaxBlobPixels]= \ -&Zone[MinBlobs]=1 \ -&Zone[MaxBlobs]= \ -&Zone[OverloadFrames]=0" -``` +:: + + curl -XPOST http://server/zm/api/zones.json -d "Zone[Name]=Jason-Newsted \ + &Zone[MonitorId]=3 \ + &Zone[Type]=Active \ + &Zone[Units]=Percent \ + &Zone[NumCoords]=4 \ + &Zone[Coords]=0,0 639,0 639,479 0,479 \ + &Zone[AlarmRGB]=16711680 \ + &Zone[CheckMethod]=Blobs \ + &Zone[MinPixelThreshold]=25 \ + &Zone[MaxPixelThreshold]= \ + &Zone[MinAlarmPixels]=9216 \ + &Zone[MaxAlarmPixels]= \ + &Zone[FilterX]=3 \ + &Zone[FilterY]=3 \ + &Zone[MinFilterPixels]=9216 \ + &Zone[MaxFilterPixels]=230400 \ + &Zone[MinBlobPixels]=6144 \ + &Zone[MaxBlobPixels]= \ + &Zone[MinBlobs]=1 \ + &Zone[MaxBlobs]= \ + &Zone[OverloadFrames]=0" + +PTZ Control APIs +^^^^^^^^^^^^^^^^ +PTZ controls associated with a monitor are stored in the Controls table and not the Monitors table inside ZM. What that means is when you get the details of a Monitor, you will only know if it is controllable (isControllable:true) and the control ID. +To be able to retrieve PTZ information related to that Control ID, you need to use the controls API + +This returns all the control definitions: +:: + + curl http://server/zm/api/controls.json + +This returns control definitions for a specific control ID=5 +:: + + curl http://server/zm/api/controls/5.json Host APIs ^^^^^^^^^^ ZM APIs have various APIs that help you in determining host (aka ZM) daemon status, load etc. Some examples: -``` -curl -XGET http://server/zm/api/host/daemonCheck.json # 1 = ZM running 0=not running -curl -XGET http://server/zm/api/host/getLoad.json # returns current load of ZM -curl -XGET http://server/zm/api/host/getDiskPercent.json # returns in GB (not percentage), disk usage per monitor (that is, space taken to store various event related information,images etc. per monitor) `` -``` +:: + + curl -XGET http://server/zm/api/host/daemonCheck.json # 1 = ZM running 0=not running + curl -XGET http://server/zm/api/host/getLoad.json # returns current load of ZM + curl -XGET http://server/zm/api/host/getDiskPercent.json # returns in GB (not percentage), disk usage per monitor (that is, space taken to store various event related information,images etc. per monitor) `` +