For any who don't know, Pingdom is a service that offers web site monitoring and notification.. a pretty sweet little application, and fairly powerful from what I've seen of it so far.
It turns out that yesterday they announced the release of their API in public beta. I love writing ColdFusion components to interact with external APIs, and as this was a new one (and one which I will certainly have a use for in various projects, and i'm fairly sure others may find it useful too) I wrote a CFC to interact with the services and API.
Pingdom API
The API itself is pretty cool, and lets you manipulate the entire system and set up monitor checks, find details on specific checks, set up users and manage notification settings. Although the API itself is split into a few sections (users, checks, settings etc) I decided to write one CFC to contain all methods and functions, instead of branching out and trying to separate various methods.
The pingdom object
The actual pingdom.cfc component is incredibly easy to instantiate and work with. At present, the API only allows for JSON responses, which although not quite opening up the full benefit of REST interfaces, is certainly enough to keep going for the moment.
You need to have an account with Pingdom to work with the API. They have paid services, but also offer a free account with limited resources; this may be enough for most people to play around with. Once you have an account, you also need to register your application to obtain an application key, which is required to proceed.
<!--- Instantiate the component ---> <cfset objPingdom = createObject( 'component', 'com.coldfumonkeh.pingdom.pingdom' ).init( emailAddress = '< email address >', password = '< account password >', applicationKey = '< application key >', parse = true ) />
In the above example, I've also set an optional fourth argument (parse) to true. This will return any response from the API as a structural representation instead of the literal string to help make debugging a little easier.
I have one 'check' with my free account, and i want to set it up to monitor my site www.mattgifford.co.uk using an HTTP request. I want it to email me AND send me a twitter message if anything goes down.
Here's how I do that:
<!--- Create a new check for my site ---> <cfset checkStatus = objPingdom.createCheck( name = 'Check My Site', host = 'mattgifford.co.uk', type = 'http', sendtoemail = true, sendtotwitter = true ) /> <cfdump var="#checkStatus#" />
There are more arguments and parameters to use so set up a whole host of different monitors and checks. You can have SMTP, Ping checks, IMAP, POP3 and more..
The response from my create request brings back the name and the id the new check:
And running a further command getCheckDetail() and passing in the returned ID of the new check, we can confirm the details have been set:
A Single Test
I want to run a quick test on a domain to make sure it's up and running. Again, there are a multitude of parameters I could send through for this, but we'll stick with another simple example.. we only want to check a standard domain is present and working.
<!--- Run a quick check on a single domain. A 'quick fix' to ensure it's up and running. ---> <cfset checkStatus = objPingdom.makeSingleTest( host = 'coldfumonkeh.com', type = 'http' ) /> <cfdump var="#checkStatus#" />
The single test is a great way to run a quick check.. the results confirm status and response time, and also which probe was used to run the test. This was selected by the system at random, although you can specify a particular probe to use, if you so desire.
There is much more to be managed and manipulated with the API, and it's a pretty cool service they're offering. I know for certain that I'll be using the CFC in many projects to come, and I hope you guys find it of use too.
Where can I get it?
The code is available to download from RIAforge.org here: http://pingdom.riaforge.org
It is also available to download and for collaboration from my github repository here: https://github.com/coldfumonkeh/pingdom-API