REST API

There is a REST API to manage your pings. With the REST API you can create new pings, update them, delete them or just get all the details about your pings.

This API is not related to your standard ping usages, it's an administration interface to manage pings programmatically. For example, you might have a service that is spread across several hosts and which needs to create new pings as the service scales up and new hosts join the network.

To use the API, you first have to enable an API key for your account. You can create an API key in your user administration area. Enable the checkbox Enable API Key and confirm your selection. Your API key will then be displayed.

When querying the API you have the send your base64 encoded API key in the Authorization header like this:

Authorization: Basic YWJjMTIz

In this example, the API key is abc123, because YWJjMTIz base64 decoded is abc123.

Ping

GET https://pidar.eu/api/v1/ping/YOUR-PING-GUID

Retrieve all information about an existing ping.

Response
{
    "guid": "<guid>",
    "name": "Name of ping",
    "interval": 3600,
    "grace_period": 10,
    "tags": ["tag-a", "tag-b"]
}

PUT https://pidar.eu/api/v1/ping

Creates a new ping. You have to send in all the required information for creating the ping. The input data has to be in JSON format.

Example Request
{
    "name": "Name of the ping",
    "interval": 3600,
    "grace_period": 60
}
Response
{
    "guid": "<guid>",
    "name": "Name of ping",
    "interval": 3600,
    "grace_period": 60
}

POST https://pidar.eu/api/v1/ping/YOUR-PING-GUID

Update an existing ping. Updates only the fields you send, keeps all other fields of the ping unchanged. The input data has to be in JSON format.

Example Request
{
    "name": "New Name of the Ping"
}
Response
{
    "guid": "<guid>",
    "name": "New Name of the Ping",
    "interval": 3600,
    "grace_period": 10,
    "tags": ["old-tag"]
}

DELETE https://pidar.eu/api/v1/ping/YOUR-PING-GUID

Delete an existing ping.

Response
{
    "status": "OK"
}

Python

We provide a Python API for PiDAR that can be used instead of calling the raw HTTP endpoints.

from pidarapi.ping import PingApi

api = PingApi('https://pidar.eu', 'your-personal-api-key')

# Create a new Ping
ping_info = api.create_ping({
    'name': 'The Name for your Ping',
    'interval': 3600,
    'grace_period': 0,
})

# And delete it again
api.delete_ping(ping_info['guid'])