This documents describes the current state of the supported REST services provided by the Plumbr Server.

General

Data format in JSON responses

Dates

dates in JSON responses are always returned as absolute timestamps represented by integer (time passed since epoch in milliseconds).

Strings

strings are formatted in UTF 8.

Authentication

Every REST service provided by Plumbr Server requires an authentication. Only HTTP Basic authentication mechanism is currently supported for external clients. Using httpie tool the username can be provided as follows:

http --auth your@mail.com https://app.plumbr.io/api/users/summary

You will be asked for the password via standard input.

Account

Although all data returned by Plumbr Server REST services is always constrained by some account, the account identifier is never passed in the request as input. Account of the currently logged in user is retrieved by a service server-side whenever such service requires it.

Date range

Any request should be accompanied by a date range. If no range is specified, then default range of "last 7 days" is used. All data, returned by Plumbr Server API, is relevant to the date range provided. If requested range is invalid, HTTP error code 400 is returned. Valid date range:

  • Starts no more than 90 days ago

  • Ends now or in the past

  • Ends after its start

  • Is no longer than 31 days

Date range can be specified in two formats – relative and absolute.

Relative time

Relative time is specified as a single parameter interpreted as an amount of hours or days in the past before the current time.

last

1h|2h|4h|12h|24h|7d|30d

last time units (h=hours, d=days) to display.

Absolute time

Absolute time is specified by two explicit time boundaries - upper and lower. Time ranges are passed in a textual form which are interpreted in an account’s time zone.

startDate

timestamp in text form: 2015-06-26T00:00

start of the date range

endDate

timestamp in text form: 2015-06-26T00:00

end of the date range

Filters

All summary queries (see examples further below in this document) can be filtered. E.g. simple query

give me a summary of user experience during last 24h

can be filtered by an application:

give me a summary of users of the given application accessed during last 24h

or by a root cause:

give me a summary of users affected by the given root cause during last 24h

To specify a filter of some query just add filter parameter to it. The general form is filter=<filterName>=<filtereValue>. E.g. for queries above (please note that the = between the name and the value should be url-encoded):

$ http GET 'https://app.plumbr.io/api/users/summary?last=24h'
$ http GET 'https://app.plumbr.io/api/users/summary?filter=applicationName%3DDashboard&last=24h'
$ http GET 'https://app.plumbr.io/api/users/summary?filter=rootCause%3D68&last=24h'

The following filters are supported:

applicationName

Any part of the application/API name

rootCause

id of the error or bottleneck.

serviceId

id of the service

serviceName

Any part of the service name

Users Summary

/api/users/summary

Gets the summary of users' activity for a given time range.

Sample request
$ http GET 'https://app.plumbr.io/api/users/summary?last=24h' \
    'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 87

{
  "total" : 9,
  "verySlow" : 3,
  "onlySlow" : 17,
  "failed" : 2,
  "success" : 3
}
Response fields description
Path Type Description

total

Number

Total number of different users seen

success

Number

Number of different users that did not have any problems

failed

Number

Number of different users who experienced failures

verySlow

Number

Number of different users who experienced very slow interactions

onlySlow

Number

Number of different users who experienced slow, but not very slow interactions

Additional examples (see also Filters)

A summary of users accessing the Dashboard application during last 24h

$ http GET 'https://app.plumbr.io/api/users/summary?last=24h&filter=applicationName%3DDashboard'

API calls summary

/api/calls/summary

Gets the summary of all monitored API calls for a given time range.

Sample request
$ http GET 'https://app.plumbr.io/api/calls/summary?last=24h' \
    'Accept:application/json'
Sample response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 87

{
  "total" : 9,
  "verySlow" : 3,
  "onlySlow" : 17,
  "failed" : 2,
  "success" : 3
}
Response fields description
Path Type Description

total

Number

Total number of API calls performed

success

Number

Number of successful API calls

failed

Number

Number of failed API calls

verySlow

Number

Number of very slow API calls

onlySlow

Number

Number of slow, but not very slow, API calls