NodePing provides a fully featured API that allows you to manage most aspects of your monitoring, as well as your customer's monitoring, through an HTTP accessible interface. The API provides the list, read, write, and delete functionality for subaccounts, contacts, contact groups, and checks, as well as the ability to get results and manage several other aspects of your account.
Access to the API is included automatically as part of all primary NodePing accounts. It is not included in SubAccounts.
The API is designed to be flexible to make it easy to use in a variety of environments. You can use REST style requests, in which case for most calls the HTTP method is used to determine the purpose for the API call. That is, GET gets a record, PUT updates a record, POST creates a new record, and DELETE removes a record. However, not all programming environments make it easy to send different HTTP methods, and we also support placing the verbs (like POST or DELETE) in the querystring. You also can choose to put all parameters in a JSON object rather than in a query string. If you send a JSON object, the parameters in the JSON will override parameters with the same name in the querystring. See the "Getting started section" below for more details.
One note on PUT vs POST. The service creates record IDs internally. This means that when you create a new record, you do not know the record ID. This means that creating a record is never idempotent because if you make the same create record call several times you will end up with a different document ID each time. To make it clear, the API uses POST for creating new records, and PUT for updating existing records. The only exception is schedules, for which update and create use identical calls and only PUT is needed.
API base url is https://api.nodeping.com/api/1/. It is generally accessed using the following URI pattern:
A token is required to use the API and must be included with each API request. The token for your account is listed in the Account Settings section of of your account. SubAccounts do not have token access.
Your token can be passed in one of three ways:
If you include a jsonp parameter in your call, results will be returned in a function named using the value of the jsonp parameter. So, for example, including jsonp=foo in your call will wrap the results in foo(); JSONP has clear security implications you should be aware of whenever you use it. You should also keep in mind that your token gives access to your account and should be shared judiciously.
We return three basic HTTP error responses.
In general we return a JSON object with errors, with the error message in a parameter called "error":
One nice thing about HTTP API's is that you can interact with them using a tool like curl, or even to a limited extent in a browser. In the examples replace "{your token}" with your actual token.
Visiting this URL will show information about your account:
To list checks associated with your account:
There are a few actions for which there is no HTTP method. For those, you use an "action" parameter. One example is the call to list subaccounts.
The action parameter can also be used for any call that you might use an HTTP method for in place of the HTTP method. For example, you could POST or GET the following address to delete the fictitious SubAccount in this example:
The same thing, but using curl to send a DELETE HTTP method and using HTTP Basic Auth would look like the following. Note the colon after the token, which prevents curl from asking you for your non-existent password.
And finally, here's a call to create a new contact record, using HTTP Basic Auth and a JSON object:
The JSON object approach looks more complicated when you're using curl, but if you are working in a programming language that already has your data in JSON it can be easier than converting the data to a query string and encoding it. For more information about the details of the calls, particular for creating records since they have the most specific field requirements, see the API Reference. Note that the phone number in the example is a made up number, which might or might not actually ring somewhere in the vicinity of Birmingham UK. Please don't call it.
There are a few different patterns for record IDs that you may see in your data. ID's are always set by the system when you create a new record. You cannot set them arbitrarily. For the most part, the information embedded in IDs is also available from the contents of the record, but since IDs are an important part of using the API knowing what the different IDs look like is helpful in working with the API.
Other than a few very early accounts (mostly those that date back to our original closed beta test phase), account IDs are based on the date and time that the account was created, followed by a random set of characters. So, for example, a typical account ID looks like this: 201203232048C76FH. Almost all other records for your account will start with your account ID. For API calls relating to your primary account, you do not need to include the account ID at all. The API knows your account ID because of your token. For calls relating to SubAccounts, the account ID is passed in the customerid parameter.
Contact IDs are the account ID followed by another segment of characters. A typical contact ID for the example account ID above might be 201203232048C76FH-IYNVG. Individual addresses inside contact records also have IDs, which are used for updating the contact. See the API Reference for details.
Contact Group IDs start with the account ID, but then have -G- and a string of characters. Again using our example account ID, a group ID might look like 201203232048C76FH-G-ISYB7.
Check IDs are very similar to contact IDs. A check record for the example account ID given above might look like 201203232048C76FH-PXMVEFJN.
Results record IDs consist of the Check IDs followed by a timestamp. So a result for our example check might be 201203232048C76FH-PXMVEFJN-1337651473175. The time stamp is based on the time that the result was generated. Individual checks do not run more frequently than once a minute, so a millisecond based ID works fine.
Notification records need a longer ID because we might generate several of them very fast. Like result records, notification record IDs include a time stamp, but they also include a randomized hash to ensure unique IDs. A notification based on the example check from the previous example might look like 201203232048C76FH-PXMVEFJN-1337617256581-e2R3J8. The first letter in that last segment denotes the notification type (this example is an email). Current notification types are 'e' for email, 's' for SMS, 'v' for voice, and 't' for twitter.
If you have questions about our API or service, please contact us at [email protected].