Manual of REST API

Manual of REST API

(English version only)

Any request URL of the REST-API of the openSpeedMonitor starts with the application path followed by the keyword /rest.
In the following manual we call this REST-base-path.
All successfully handled requests return their result in JSON notation. Default output format is not pretty-printed (small in size). A pretty-printed output can be forced with an URL query argument pretty=true.


GET Method: Results between

Request signature

[REST-base-path]/[system]/resultsbetween/[timestampFrom]/[timestampTo]

The request URL starts with the REST-base-path followed by the system name (remember special chars like whitespace need to be URL escaped which was left out here for readability), followed by the methods name /resultsbetween, followed by the requested time-frame in the ISO 8601 format given as /start/end

Example URI for the system "live" and the time-frame 1st January 2014, 0 AM to the 1st January 2014, 11 PM (UTC): [REST-base-path]/live/resultsbetween/20140101T000000Z/20140101T230000Z

You can obtain a list of all systems by sending a request to [REST-base-path]/allSystems. As result a JSON list of system names is returned.

Additional parameters

To make a more concrete request, you may add one or more of the following arguements as URL query arguments.

page
OPTIONAL
The name of a page. If specified only results belonging to this page are returned. If parameter page and pageId are both provided pageId is used.
You can obtain a list of all pages by sending a request to [REST-base-path]/allPages. As result a JSON list of pages is returned.
pageId
OPTIONAL
The ID of a page. If specified only results belonging to the page of this ID are returned. If parameter page and pageId are both provided pageId is used.
You can obtain a list of all pages by sending a request to [REST-base-path]/allPages. As result a JSON list of pages is returned.
step
OPTIONAL
The name of a (measured) step. If specified only results belonging to this step are returned.
You can obtain a list of all steps by sending a request to [REST-base-path]/allSteps. As result a JSON list of steps is returned.
stepId
OPTIONAL
The ID of a (measured) step. If specified only results belonging to the step of this ID are returned. If parameter step and stepId are both provided stepId is used.
You can obtain a list of all steps by sending a request to [REST-base-path]/allSteps. As result a JSON list of steps is returned.
browser
OPTIONAL
The name of a browser. If specified only results belonging to this browser are returned.
You can obtain a list of all browsers by sending a request to [REST-base-path]/allBrowsers. As result a JSON list of browsers is returned.
browserId
OPTIONAL
The ID of a browser. If specified only results belonging to the browser of this ID are returned. If parameter browser and browserId are both provided browserId is used.
You can obtain a list of all browsers by sending a request to [REST-base-path]/allBrowsers. As result a JSON list of browsers is returned.
location
OPTIONAL
The location-address of a location. If specified only results belonging to this location are returned.
You can obtain a list of all location-addresses by sending a request to [REST-base-path]/allLocations. As result a JSON list of locations is returned.
To get inactive locations as well use [REST-base-path]/allLocations?showInactive=true.
locationId
OPTIONAL
The ID of a location. If specified only results belonging to the location of this ID are returned. If parameter location and locationId are both provided locationId is used.
You can obtain a list of all location-addresses by sending a request to [REST-base-path]/allLocations. As result a JSON list of locations is returned.
cachedView
OPTIONAL
The cached view. If specified only results of this cached view are returned.
Only one of the following two values are allowed:

An example with all parameters:
[REST-base-path]/live/resultsbetween/20140101T000000Z/20140101T230000Z?
browser=IE&page=WK&location=Hetzner01-IE&step=IE8_BV1_Step06_Warenkorb - hetzner&cachedView=UNCACHED

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains a list of results matching the given request-parameters.

Response example:
[{
    "executionTime": "2014-07-02T00:01:12Z",
    "csiValue": "0,93",
    "docCompleteTimeInMillisecs": 2448,
    "numberOfWptRun": 1,
    "cachedView": "UNCACHED",
    "page": "HP",
    "step": "Homepage",
    "browser": "Firefox",
    "location": "prod-rz1:Firefox",
    "detailUrl": "http://wptserver-url.com/result/test-id"
},
{
    "executionTime": "2014-07-02T00:01:12Z",
    "csiValue": "1,00",
    "docCompleteTimeInMillisecs": 1310,
    "numberOfWptRun": 1,
    "cachedView": "CACHED",
    "page": "HP",
    "step": "Homepage",
    "browser": "Firefox",
    "location": "prod-rz2:Firefox",
    "detailUrl": "http://wptserver-url.com/result/test-id"
}]

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
The end of the requested time frame is before the start of it. For sure, this is invalid. The end of the time-frame need to be after its start. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 413 Request Entity Too Large
The requested time-frames duration in days is wider than 2 days. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
If at least one of the requested elements was not found. If no further parameters specified, this need to be the specified system otherwise it could be any of them. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

GET Method: JobGroup CSI

Request signature

[REST-base-path]/[system]/csi/[timestampFrom]/[timestampTo]

The request URL starts with the REST-base-path followed by the system name (remember special chars like whitespace need to be URL escaped which was left out here for readability), followed by the methods name /csi, followed by the requested time-frame in the ISO 8601 format given as /start/end

Example URI for the system "live" and the time-frame 1st January 2014, 0 AM to the 1st January 2014, 11 PM (UTC): [REST-base-path]/live/csi/20140101T000000Z/20140101T230000Z

You can obtain a list of all systems by sending a request to [REST-base-path]/allSystems. As result a JSON list of system names is returned.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains the over-all customer satisfaction index for the requested system and period.

Response example:
{
    "csiValueAsPercentage":90.5265687342499,
    "targetCsiAsPercentage":90,
    "delta":0.5265687342499064,
    "countOfMeasurings":174
}

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
The end of the requested time frame is before the start of it. For sure, this is invalid. The end of the time-frame need to be after its start. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 413 Request Entity Too Large
The requested time-frames duration in days is wider than 8 days. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
If the specified system was not found. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

GET Method: Page CSI

Request signature

[REST-base-path]/[system]/[page]/csi/[timestampFrom]/[timestampTo]

The request URL starts with the REST-base-path followed by the system (aka JobGroup) name (remember special chars like whitespace need to be URL escaped which was left out here for readability), followed by the page name, followed by the methods name /csi, followed by the requested time-frame in the ISO 8601 format given as /start/end

Example URI for system "live", page "homepage" and the time-frame 1st January 2014, 0 AM to the 1st January 2014, 11 PM (UTC): [REST-base-path]/live/homepage/csi/20140101T000000Z/20140101T230000Z

You can obtain a list of all systems by sending a request to [REST-base-path]/allSystems. As result a JSON list of system names is returned. You can obtain a list of all pages by sending a request to [REST-base-path]/allPages. As result a JSON list of page names is returned.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains the over-all customer satisfaction index for the requested system, page and period.

Response example:
                            {
                            "csiValueAsPercentage":90.5265687342499,
                            "targetCsiAsPercentage":90,
                            "delta":0.5265687342499064,
                            "countOfMeasurings":174
                            }

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
The end of the requested time frame is before the start of it. For sure, this is invalid. The end of the time-frame need to be after its start. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 413 Request Entity Too Large
The requested time-frames duration in days is wider than 8 days. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
If specified system or page were not found. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

GET Method: Get CsiConfiguration

Request signature

[REST-base-path]/csi/csiConfiguration

The request URL consists of REST-base-path the word csi and the name of the method csiConfiguration.

Parameters

id
MANDATORY
The unique id of the csiConfiguration

Potential outcomes of a request

[timestampFrom]
HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains the complete csiConfiguration.

For this REST-method is no example-response given, because it's too long for this side. The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
One of the query arguments is missing. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

GET Method: Get names for ids for several domains

Request signature

[REST-base-path]/domain/namesForIds/[requestedDomains]

The request URL consists of REST-base-path the word domain and the name of the method namesForIds.

Example URI for the JobGroups with id 1 and 2 [REST-base-path]/domain/namesForIds/%7B%22JobGroup%22%3A%5B1%2C2%5D%7D

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains all requested domains. They again map the requested ids to the names.
Response example:
{"Target":
    {"JobGroup":
        {
        "1":"NameForJobGroupWithId1",
        "2":"NameForJobGroupWithId2"
        }
    }
}

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
One or more requested domains doesn't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

GET Method: Get ids for names for several domains

Request signature

[REST-base-path]/domain/idsForNames/[requestedDomains]

The request URL consists of REST-base-path the word domain and the name of the method idsForNames.

Example URI for the browsers with name chrome and firefox [REST-base-path]/domain/idsForNames/%7B"Browser"%3A%5B"Chrome"%2C"Firefox"%5D%7D

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains all requested domains. They again map the requested ids to the names.
Response example:
{"Target:"
    {"Browser":
        {
        "1":"NameForBrowserWithId1",
        "2":"NameForBrowserWithId2"
        },
    "Page":
        {
        "1":"NameForPageWithId1",
        "2":"NameForPageWithId2"
        }
    }
}

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
One or more requested domains doesn't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

GET Method: Translate to Customer Satisfaction

Request signature

[REST-base-path]/csi/translateToCustomerSatisfaction

The request URL consists of REST-base-path the word csi and the name of the method translateToCustomerSatisfaction.

Parameters

pageName
MANDATORY
The name of the page the doc complete time was measured for.
loadTimeInMillisecs
MANDATORY
Load time to translate to customer satisfaction.
csiConfiguration
OPTIONAL
The name of the csiConfiguration to use for calculation. If omitted a system has to be given instead.
system
OPTIONAL
The name of the measurement system to use for calculation. If omitted a csiConfiguration has to be given instead.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains the calculated customer satisfaction for the given load time.

Response example:
{"target":
    {
        "loadTimeInMillisecs":3500,
        "customerSatisfactionInPercent":0.75837
    }
}

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
One of the query arguments is missing or no page could be found for given pageName. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

GET Method: Result URL's of job

Request signature

[REST-base-path]/job/[job-id]/resultUrls/[timestampFrom]/[timestampTo]

The request URL starts with the REST-base-path followed by job/, the ID of the measurement job to get result url's for, method name /resultUrls and the two timestamps for start and end of the period of interest. Timestamps have to match ISO 8601 format.

Example URI to get URL's to visualize results of measurement job with ID 42 from 23rd of july 2014, 09:00 AM to 24th of july 2014, 02:23 AM: [REST-base-path]/job/42/resultUrls/20140723T090000Z/20140724T022300Z

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains three URL's of OpenSpeedMonitor that visualize results of requested measurement job for period between the two given timestamps.

Response example:
{
    "job": "my-measurement-job",
    "from": "2014-11-01T01:00:00+01:00",
    "to": "2014-11-01T03:00:00+01:00",
    "results-chart-url":"[URL to result dashboard of OpenSpeedMonitor]",
    "csi-chart-url":"[URL to csi dashboard of OpenSpeedMonitor]",
    "results-tabular-url": "[URL to tabular view in OpenSpeedMonitor]"
}

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
The end of the requested time frame is before the start of it. For sure, this is invalid. The end of the time-frame need to be after its start. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not found
No job with requested job ID can be found.
The response is of type text/plain (encoding UTF-8).

PUT Method: Job activation

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

[REST-base-path]/job/[job-id]/activate

The request URL starts with the REST-base-path followed by job/, the ID of the measurement job to activate and the methods name /activate.

Example URI to activate measurement job with ID 42 would be [REST-base-path]/job/42/activate

Parameters

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains the json representation of the activated measurement job.
The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
This function requires an api key. You missed to submit one as parameter. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
Either submitted api key or job with submitted id don't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 403 Forbidden
Submitted api key doesn't have permission to activate measurement jobs or is generally invalid. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

PUT Method: Job deactivation

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

[REST-base-path]/job/[job-id]/deactivate

The request URL starts with the REST-base-path followed by job/, the ID of the measurement job to activate and the methods name /deactivate.

Example URI to deactivate measurement job with ID 42 would be [REST-base-path]/job/42/deactivate

Parameters

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains the json representation of the deactivated measurement job.
The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
This function requires an api key. You missed to submit one as parameter. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
Either submitted api key or job with submitted id don't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 403 Forbidden
Submitted api key doesn't have permission to deactivate measurement jobs or is generally invalid. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

PUT Method: Set Execution Schedule

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

[REST-base-path]/job/[job-id]/setExecutionSchedule

The request URL starts with the REST-base-path followed by job/, the ID of the measurement job to activate and the methods name /setExecutionSchedule.

Example URI to set execution schedule of measurement job with ID 42 would be [REST-base-path]/job/42/setExecutionSchedule

Body

The body of the PUT request must consist of a json containing the execution schedule to set.
Example body to let respective job run every two minutes:

{"executionSchedule": "* */2 * * * ? *"}
See Quartz documentation for cron syntax of schedule.

Parameters

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, a result in JSON notation is returned. It contains the json representation of the measurement job with the new execution schedule.
The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
Reasons can be the absence of an api key as parameter or of an execution schedule in the body of the request. Also an invalid schedule will result in a 400. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
Either submitted api key or job with submitted id don't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 403 Forbidden
Submitted api key doesn't have permission to set execution schedule of measurement jobs or is generally invalid. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

Method: Create event

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

The request URL starts with the REST-base-path followed by event/create.

Example URI to create a new event would be [REST-base-path]/event/create Created events have a timestamp and are shown as vertical lines in diagrams of OpenSpeedMonitor dashboards.

Parameters

Attributes of event to be created must be sent as query arguments.

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.
shortName
MANDATORY
Short name of event to be created. This is shown on hover popup of dasboards.
description
OPTIONAL
More detailed description of event to be created. This is shown on hover popup of dasboards.
system
MANDATORY
Name of the measurement system the created event should be associated to. Can be more than one system. You can obtain a list of all systems by sending a request to [REST-base-path]/allSystems. Created events are shown only in dashboard views for respective system (except events with global visibility, see following parameter).
globallyVisible
OPTIONAL
Normally events are only shown in dashboard views for associated systems. Globally visible events are shown on all dashboards. Only the following values are allowed:
  • true
    Created events are visible on all dashboard sights independent of chosen systems.
  • false
    Created events are only visible on dashboard sights of systems associated to event (see parameter system). This is the default.
eventTimestamp
OPTIONAL
The timestamp the event occurred. If omitted the timestamp this api function is called is used as timestamp for the event.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully, an event gets created and persisted. This event in JSON notation is returned.
Response example:
{
"class": "de.iteratec.osm.report.chart.Event",
"description": "my-description",
"eventDate": "2015-05-12T13:31:03Z",
"globallyVisible": false,
"jobGroups":
    [
        {
            "class": "JobGroup",
            "id": 2
        },
        {
            "class": "JobGroup",
            "id": 7
        }
    ],
"shortName": "my-event"
}

The response is of type application/json (encoding UTF-8) as described in RFC4627.
HTTP status 400 Bad Request
One of the mandatory parameters was omitted or the timestamp parameter had the wrong format. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

PUT Method: Measurement activation

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

[REST-base-path]/config/activateMeasurementsGenerally

The request URL starts with the REST-base-path followed by config/activateMeasurementsGenerally.

Parameters

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully. The measurements got enabled generally, no matter whether they were enabled before or not.
HTTP status 400 Bad Request
This function requires an api key. You missed to submit one as parameter or the key doesn't have permission to activate measurements. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
Submitted api key doesn't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 403 Forbidden
Submitted api key is generally invalid. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

PUT Method: Measurement deactivation

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

[REST-base-path]/config/deactivateMeasurementsGenerally

The request URL starts with the REST-base-path followed by config/deactivateMeasurementsGenerally.

Parameters

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully. The measurements got disabled generally, no matter whether they were enabled before or not.
HTTP status 400 Bad Request
This function requires an api key. You missed to submit one as parameter or the key doesn't have permission to activate measurements. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
Submitted api key doesn't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 403 Forbidden
Submitted api key is generally invalid. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

PUT Method: NightlyDatabaseCleanup activation

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

[REST-base-path]/config/activateNightlyDatabaseCleanup

The request URL starts with the REST-base-path followed by config/activateNightlyDatabaseCleanup.

Parameters

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully. The nightly-cleanup got enabled generally, no matter whether they were enabled before or not.
HTTP status 400 Bad Request
This function requires an api key. You missed to submit one as parameter or the key doesn't have permission to activate nightlyDatabaseCleanup. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
Submitted api key doesn't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 403 Forbidden
Submitted api key is generally invalid. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).

PUT Method: NightlyDatabaseCleanup deactivation

 THIS METHOD IS PROTECTED: You need a valid api key, ask your osm administrator for one.

Request signature

[REST-base-path]/config/deactivateNightlyDatabaseCleanup

The request URL starts with the REST-base-path followed by config/deactivateNightlyDatabaseCleanup.

Parameters

apiKey
MANDATORY
An api key for OpenSpeedMonitor. Provides permissions for api functions.

Potential outcomes of a request

HTTP status 200 OK
The request handled successfully. The measurements got disabled generally, no matter whether they were enabled before or not.
HTTP status 400 Bad Request
This function requires an api key. You missed to submit one as parameter or the key doesn't have permission to deactivate nightlyDatabaseCleanup. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 404 Not Found
Submitted api key doesn't exist. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).
HTTP status 403 Forbidden
Submitted api key is generally invalid. An error message with details is attached as response.
The response is of type text/plain (encoding UTF-8).