API

This is community documentation for the API. To see official documentation, review zoneminder.readthedocs.org. Users reading this doc may also want to read the wiki page for ZMNinja.

Test API is Working (1.32+)

Use this command if you've enabled authentication.

curl -X POST -d "user=somename&pass=somepass" http://serverip/zm/api/host/getVersion.json

Make sure all of this is included. It is not necessary to use login.json before running this command. The ampersand must be between user and pass. If you aren't using authentication then use the following:

curl -X GET http://serverip/zm/api/host/getVersion.json

If you are having further trouble, try searching the forum or possibly enabling debugging in cakephp, and also in the web server.

SSL Configuration

Related to the API, if you wish to have some encryption, refer to /etc/apache2/ports.conf You will see that it requires the ssl module, and the symbolic link.

a2enmod ssl

Add the symbolic link for /etc/apache2/sites-available/default-ssl.conf to sites-enabled.

And uncomment / enable SSLEngine, SSLCertificateKey, and SSLCertificateKeyFile in /etc/apache2/sites-available/default-ssl.conf.

You may optionally want to generate a new SSL key.

Setting up self signed SSL certs for apache2 is a common sysadmin task that will not be covered in this guide. Search online for more info.

Examples

Adjusting Monitor from Modect to Monitor

Start motion detection on monitor 3
/usr/bin/curl -XPOST http://localhost/zm/api/monitors/3.json -d "Monitor[Function]=Modect&Monitor[Enabled]=1"
Stop motion detection on monitor 3
/usr/bin/curl -XPOST http://localhost/zm/api/monitors/3.json -d "Monitor[Function]=Monitor&Monitor[Enabled]=1"

from: https://forums.zoneminder.com/viewtopic.php?t=32771

Configuring CakePHP for "x webserver"

Having recently setup the API for lighttpd, I found the following was necessary in order to get it to work properly. Perhaps this information will assist someone else who isn't using Apache / Nginx / Lighttpd as the configuration should be similar for any webserver that supports PHP, aliases and rewrites.

Alias'

First off the webroot for zm may look something like this:

/usr/share/zoneminder/www$ ls
ajax  css    graphics  index.php  lang        skins  vendor
api   fonts  includes  js         robots.txt  tools  views

What you need to know is that the api is NOT at /usr/share/zoneminder/www/api but in fact is located at

/usr/share/zoneminder/www/api/app/webroot

So clients to the webserver will navigate to yourserverip/zm/api but the webserver will deliver yourserverip/www/api/app/webroot assuming that www == zm. (in apache, this is handled by /etc/apache2/conf-available/zoneminder.conf with Alias /zm /usr/share/zoneminder/www) The API is handled in a similar manner. Instead of aliasing /zm to /usr/share/zoneminder/www/ there will be an alias from /zm/api to /usr/share/zoneminder/www/api/app/webroot. Yes, it is confusing that there is a folder named API that is NOT the API, when in fact the webroot folder is the API. Don't ask me. I didn't design it. Apache doesn't help with its verbose configuration, compared to the leaner config found in lighttpd which is more intuitive.

So now we have the following

requests to myserver/zm  go to /usr/share/zoneminder/www/
requests to myserver/api go to /usr/share/zoneminder/www/api/app/webroot

Rewrites

The final thing you need to understand is that CakePHP has a single index.php file that does all the work for the API. So when you request http://serverip/zm/api/host/getVersion.json what is actually happening is that the server will pass /host/getVersion.json to /zm/api/index.php, and index.php will do its black magic to get the ZM version. This is because if you try to navigate directly to http://serverip/zm/api/host/getVersion.json (without a rewrite rule in place) you will get a 404, because there is no such file in /www/api/app/webroot. How this is handled in the web servers is there is a rewrite rule (not an alias this time) that takes anything that is /zm/api-whatever (the regex covers everything after /zm/api) and changes it to /zm/api/index.php. Then this index.php handles the request.

In apache this rule looks like:

RewriteEngine On
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteRule ^ index.php [L]
   RewriteBase /zm/api

In lighttpd this rule looks like:

url.rewrite = (
     "^/zm/api(.+)$"           =>              "/zm/api/index.php"
)

I'm not entirely sure how the apache one works, but lighttpd is a (pcre) regex with ^-start with /zm/api then (.+) any number of characters to the end $ then change to /zm/api/index.php. Essentially, any request that is /zm/api-whatever will be converted to /zm/api/index.php.

Troubleshooting

curl -X GET http://serverip/zm/api/host/getVersion.json returns with 'page not found'

Check that you have an up to date copy of the /etc/apache2/conf-available/zoneminder.conf file. If in doubt, compare to a working installation. I recently had a case, where the zoneminder.conf file was missing some of the configurations (it must've been from migrating an older ZM to 1.36), it should be around 50+ lines of code for 1.36. Also make sure the appropriate apache modules are enabled (a2enmod rewrites, a2enmod cgi, and there are some others, see wiki.zoneminder.com/Debian).

See Also

• ZMNinja