API Documentation

Dog Ear's API lets you check server status, add, remove, and update servers. We also support alerts via webhooks (paid plans only), which can be configured when creating or editing a server. This API is a simple HTTP API that expects and returns JSON.

Important Notes

You must set the "Content-Type" header to "application/json." e.g. Content-Type: application/json

This API uses HTTP token based authentication. The token is your api key, which must be set as the value of the "Authorization" header.

Sign in to see your api key.

All requests must set an "Authorization" header. e.g. Authorization: Token token={your api key}.

The root URL for the API is https://dogear.io/api/v1. The endpoints below should concatenated with this URL.

Endpoints

GET /servers

Returns a list of servers and their latest status.

Sample response:

{
  "servers": [
    {
      "id": 1,
      "user_id": 1,
      "name": "google",
      "url": "http://google.com",
      "http_method": "GET",
      "headers": [
        {
          "name": "User-Agent",
          "value": "dogear.io / woof / 1.0.0"
        }
      ],
      "body": "",
      "alert_phone_numbers": [],
      "alert_emails": [
        "you@yourdomain.com"
      ],
      "last_status": "up",
      "last_status_checked_at": "2016-05-01T17:56:04.493Z",
      "check_interval": 5,
      "disable_ssl_validation": false,
      "webhook_url": null
    },
    ...
  ]
}

POST /servers

Adds a new server (URL) to be monitored by Dog Ear. Returns an error if you're at your plan's limit.

Parameters:

Parameter Name Type Required Notes
name string Yes The display name of the server
url string Yes The URL to monitor
http_method string Yes Possible values are "GET" or "POST"
headers array of hashes No See sample for expected format
body string No Only used when http_method is "POST"
alert_emails array Yes* See sample for expected format. One of alert emails, phone numbers, or webhook URL is required.
alert_phone_numbers array Yes* See sample for expected format. One of alert emails, phone numbers, or webhook URL is required. Only used by paid plans.
webhook_url string Yes* Dog Ear will POST to this URL if your server status changes from down to up or up to down. One of alert emails, phone numbers, or webhook URL is required. Only used by paid plans.
disable_ssl_validation boolean No False by default. This should only be used if you're using a self-signed certificate.

These parameters must be wrapped in a "server" object that is passed as the request body. For example:

{
  "server": {
      "name": "google.com",
      "url": "http://google.com",
      "http_method": "GET",
      "headers": [
        {
          "name": "User-Agent",
          "value": "dogear.io / woof / 1.0.0"
        }
      ],
      "alert_emails": ["you@yourdomain.com"]
    }
}
      

Sample response:

{
  "server": {
    "id": 13,
    "user_id": 1,
    "name": "google",
    "url": "http://google.com",
    "http_method": "GET",
    "headers": [
      {
        "name": "User-Agent",
        "value": "dogear.io / woof / 1.0.0"
      }
    ],
    "body": null,
    "created_at": "2016-05-13T02:09:53.215Z",
    "updated_at": "2016-05-13T02:09:53.215Z",
    "alert_phone_numbers": ["12225551212"],
    "alert_emails": ["you@yourdomain.com"],
    "last_status": "unknown",
    "last_status_checked_at": "2016-05-13T02:07:53.214Z",
    "check_interval": 5,
    "disable_ssl_validation": null,
    "webhook_url": null
  }
}
      

Note: The status will always be "unknown" immediately after creation. The status will be updated once Dog Ear has checked checked your URL for the first time.

PUT or PATCH /servers/{id}

Updates the server with the specified id.

Parameters:

Parameter Name Type Required Notes
id integer Yes part of URL

See the documentation for creating a server for a list of all parameters. You can pass only the parameters you want to change. For example, you can update only the name of a server. Note that any array or hash fields that are passed (e.g. headers, alert_emails, alert_phone_numbers) will be replaced wholesale on update.

Sample Response:

See the documentation for creating a server for a sample response.

DELETE /servers/{id}

Deletes the server with the specified id.

Parameters:

Parameter Name Type Required Notes
id integer Yes part of URL

Sample Response:

HTTP 204 (no content) if successful. HTTP 404 (not found) if the server was not found.

© 2015-2018 Code Swiftly, LLC. All rights reserved. Sign up for our mailing list.