The heart of the CronAlarm system is the API. We offer a simple API that is available to all plans, and an advanced API that is available for the Professional and Enterprise plans.
Since every job in the CronAlarm system is assigned a unique API key, you'll need that information before you can call the API. For more information about managing your jobs and API keys, see our Jobs documentation. For the examples on this page, we'll assume our API key is "12345".
The API works by calling a URL at the beginning of your job and then again at the end. From this information, at a minimum the CronAlarm platform will be able to monitor when your job last ran, and how long it took to complete it's task. The difference between the simple and advanced API is that what additional information, if any, can be reported from by you.
If your only concern is when your job runs and how long it takes to run, the simple API is all you need. The simple API consists of 2 GET requests. Here is a quick example (again, let's assume our API key is "12345"):
curl https://api.cronalarm.com/v2/12345/start
# do your stuff here
curl https://api.cronalarm.com/v2/12345/end
As you can see, the API url follows the following format: https://api.cronalarm.com/v2/<your api key>/(start|end). You'll want to call the /start API url at the beginning for your job, and the /end API url at the end of your job.
With just those 2 lines of code added to your job, CronAlarm will be able to determine when your job ran, and how long it took to run. CronAlarm will then compare the results to any metrics you've defined for runtime alerts, and if anything outside of your settings is detected, CronAlarm will send alerts.
Some users find the simple API sufficient for their needs. However, CronAlarm also offers an advanced API that allows you to take your cron monitoring up a notch.
Here is how it's done. You start out with a simple GET request just like you did in the simple API example:
curl https://api.cronalarm.com/v2/12345/start
# do your stuff here
So far, so good, right? This time, however, at the end of your code you can do a POST request to the CronAlarm API and send in some additional information. The API takes 4 arguments (all are optional, so you only need to use what you want):
Below is an example of accessing the advanced API to report an error:
curl -X POST -H 'Content-type: application/json' --data '{"success": "0", "server": "webserver1", "path": "/var/www/ftptransfer.js", "message": "failure to connect to remote server"}' https://api.cronalarm.com/v2/12345/end
Getting an error report that tells you the job called 'file transfer' failed is nice. But getting an error report that tells you job 'file transfer' failed on server 'webserver1' located at '/var/www/ftptransfer.js' is pretty cool and much more helpful. If you manage jobs that run on multiple servers you'll really appreciate this additional information.
The CronAlarm API will return standard HTTP response codes to indicate the status of you request. You can use these response codes to help troubleshoot any issues you may be having on your end.