From 71665a331568faefa437c3b8c080d7074273a3e9 Mon Sep 17 00:00:00 2001 From: Pliable Pixels Date: Sun, 14 Jun 2015 11:21:00 -0400 Subject: [PATCH] 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) `` +