API User Guide

1. Introduction
2. Overview
3. API Key
4. Constructing Your Query – The Query Builder Tool
Accessing the Query Builder
Using the Query Builder
5. Response
6. Example Queries
7. Using Your Query

Appendices

A. Examples of API Implementations
B. Query Builder Screen
C. Query Builder Arguments Screen
D. Troubleshooting Guide

1. Introduction

The API is predominantly a data extraction tool that allows NCC Group Web Performance customers to directly access and extract their test results through standard HTTP requests in a variety of formats such as XML, JSON, PHP or YAML. API data requests can be used in anything from reporting spreadsheets through to live reporting applications, and the API is the recommended solution for advanced Monitoring customers to import live and historic data.

This document explains the steps involved in using the API to extract monitoring data from your accounts.

NOTE: The API can also be used to directly update certain aspects of your monitoring configuration. This functionality is explained in a separate document available here.

2. Overview

Queries to the API are in the form of an HTTP request. The API provides a user interface that assists you in designing and fine-tuning your query. You control how much of your data you want returned and work towards the query that provides you with the data you require. Then, depending upon your requirements, you can either run this query manually as and when required or build an application to call it programmatically, either on an ad hoc manual basis or on an automated scheduled basis. Your applications can also be designed to refine the extracted data further if required and/or present it in a bespoke report format that suits your exact business needs.

See Appendix A for examples of how the API has been used.

The key steps in using the API user interface are:

  • Access the API user interface starting page at https://api.siteconfidence.co.uk/
  • Log in with your standard username and password. At this point an authentication token referred to as an ‘API Key’ is generated that validates your session
  • Use the interface to construct your query
  • Run your query to display the data that will be returned
  • Modify and re-run your query as many times as necessary until the data returned is as you require

3. API Key

As mentioned above, once you have logged into the user interface the API uses a key to maintain a session. This key is unique to each session and is an essential component of the query URL that is sent to the API.

The key remains valid for 60 minutes since last use. This means a session can last indefinitely if the key is used a minimum of once every 59 minutes. Should the key expire, you must re-perform the authentication process so that a new key can be assigned. When using the user interface this simply means logging in again.

NOTE: The API key will automatically expire if the account’s access to the API expires or is removed. Should this happen unexpectedly, please contact your Account Manager or Customer Support. If for any reason you need to force a key to expire, this can be done via a URL request in your browser. If you have been assigned key abcdefghijklmnopqrstuvwxyz123456 and wish to expire this, then the URL request would be:

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Logout

4. Constructing Your Query – The Query Builder Tool

In order to return the specific data you require from the API, the query URL needs to include values that filter the results data in some way. To facilitate the process of defining the required filters, we have therefore developed the Query Builder tool. This is part of the API user interface and comprises a screen on which you select the data you require and then constructs the correct query URL for you.

Accessing the Query Builder

1. Access the API user interface starting page at https://api.siteconfidence.co.uk/

This will display the Login screen:

api1

2. Log in with your portal username and password

Enter your portal username and password. Your API key is generated for you at this point.

In order to access the API, you will need an NCC Group Web Performance account that has been granted API privileges. If you are not sure if your account has these privileges, please contact your Account Manager.

3. Select version

Once you have logged in, you will be presented with the following screen:

api2

Under the ‘Query Builder’ option select the ‘current’ version, which will normally be the only option available. At times there may also be a ‘dev’ option displayed – this is presented when newly developed API features are being trialled and you should select this only if you are participating in that particular trial.

NOTE: As well as the ‘Query Builder’ option you will notice that there is also an ‘API direct call (XML output)’ option. Selecting this just provides an API Key and then leaves you to build your own query unassisted. Once you are confident with how queries are constructed you can use this instead of the Query Builder if you prefer.

The Query Builder screen will be opened in a new tab or window, depending upon your browser.

Using the Query Builder

The Query Builder screen looks like this:

api3

NOTE: The above shows just the main part of the screen. The complete screen can be seen in Appendix B.

From this page you can build a query string URL that will provide access to the monitoring data in which you are interested. The area bordered in red in the screenshot is the Query String Preview Area and displays a preview of this URL. When you first access the Query Builder, the URL defaults to the URL of the API appended with the assigned API key. However, as you start to construct the query using the Query Builder tool, you will see the URL change to reflect the choices you make.

Note that the Query Builder screen also clearly shows the API Key that has been generated for you for the current session, as can been seen by the area bordered in green in the screenshot. As mentioned before, this key is valid for 60 minutes from its last use. If at any time whilst using the Query Builder it appears to become unresponsive when trying to select the test filters or data filters outlined below, then your key may have expired. In this case try refreshing the screen (F5) to see if a 401 authentication failure message is displayed. If so, then the key has indeed expired, in which case you will need to log into the API again to generate a new one.

1. Specify the test filters

The test filters are the fields bordered in blue in the screenshot and they allow you to define the monitoring tests in which you are interested. Try to be as atomic as possible in your selection, as the more specific the criteria the faster the query will run.

A brief description of each filter is provided beneath its respective field. You can also click on the ‘Arguments’ tab to display a single page of all the filters and their descriptions, and a copy of this page can be found in Appendix C. Some useful additional information on the key fields that require completion also now follows:

  • AccountId
    • Choose the monitoring accounts from which you wish to view data by using this drop-down.
    • The accounts available in the drop-down are those to which you have access via your passport.
    • You can choose either single or multiple accounts.
  • Id
    • Choose the monitors from which you wish to view data by using this drop-down.
    • The monitors available in the drop-down are those that reside within the account(s) selected in the AccountId drop-down. Therefore you must have selected at least one account in the AccountId field in order for the Id drop-down to present you with any options.
    • You can choose any combination of the monitors available.
    • For monitors with multiple steps (e.g. user journeys) you can select individual steps so that only data for those steps will be returned by the query.

NOTE: If you have selected an account but the Id drop-down presents no options, then it may be that an API query allowance has not been set for your company. To verify this, please exit the API and try to log in again, at which point you will be notified if your allowance has not been set. In this event please contact your Account Manager or Customer Support.

  • StartDate
    • Specify the start date for the test data you wish to retrieve.
    • You can enter this in yyyy-mm-dd format or you can use the date picker pop-up.
    • If you do not specify a start date, the query will use a default date of 7 days ago.
  • EndDate
    • Specify the end date for the test data you wish to retrieve.
    • You can enter this in yyyy-mm-dd format or you can use the date picker pop-up.
    • If you do not specify an end date, the query will use a default date of the current date.
  • LimitTestResults
    • Specify the maximum number of test results that you wish to return. The default value is 20.
    • Whilst you are constructing your query we recommend that you leave this as the default value or set it even lower so that your test queries run as quickly as possible.

All the remaining fields are optional and are provided as a means of narrowing down your test criteria still further.

One of these optional fields that is particularly worth pointing out is the Format field at the very bottom of the page. This allows you to specify the format of the returned data and you can choose from XML, JSON, PHP or YAML. Typically most customers will use the default XML option whilst constructing their queries through the Query Builder as this format is the most human-readable, but if ultimately you require the response to be in one of the other formats then you can specify that format here as a final adjustment to your query.

2. Specify the data filters

Once you have defined the tests in which you are interested, use the Return drop-down (bordered in orange in the screenshot) to select the data items for these tests that you wish to be returned in the response. As with the test filter fields, smaller datasets reduce the size of the resulting response and will improve the performance of your query, so try to be as specific as you can.

The data item list is a tree representation of the NCC Group monitoring platform data structure. This list is generated dynamically based on the test filters you have selected. For example, the data structure for the test results of page monitors is different from that of user journeys, so the tree will look different depending upon whether page monitors, user journeys or both have been included in the query. Note therefore, that if you make a change to the types of monitors in your query, the tree will be re-generated and any data items you have previously selected may be lost. Also, certain branches of the tree are displayed only if there is data held within them so, for example, if you specify a date range for your query during which no tests were run (e.g. because all selected monitors were disabled), then the branches of the tree that relate to test result data will not appear.

Because the API is designed to provide you with access to the whole range of data on our monitoring platform, the number of data items available for selection is extensive. However, a familiarity with the monitoring portal and the data available there makes much of the data filter selection for an API query logical and intuitive. Nevertheless, there are a few key aspects of the tree structure that are worth highlighting:

Beneath the main Account level there are separate branches for monitors of different types, such as page monitors, user journeys and web services monitors.

api4

Page monitors are monitors for a single web page, whereas user journeys and web services monitors are multi-step tests that monitor a sequence of pages. Therefore, for the latter two types of monitor, the next level within the tree provides overall monitor-level information. E.g. for user journeys this is the ‘UserJourney’ node:

api5

Within this monitor-level node you will then find a ‘Steps’ branch that holds the data for each individual page that is tested by the monitor:

api6

The structure of this Steps node is then essentially identical to the structure of the aforementioned Pages node that contains data for single page monitors.

At monitor-level and page-level there are ‘TestResults’ and ‘TestingSummary’ branches. TestResults contains information relating to specific tests, whereas TestingSummary can provide you with data averaged over standard periods or just the data relating to the last test that was run. The summary data can therefore be particularly useful, depending upon your business needs.

5. Response

Once you have constructed your query, click on the URL link in the Query String Preview Area to run your query. This opens a new tab or window, depending upon your browser, in which the query results are displayed. This can be done at any point during the query compilation process and will enable you to continually refine your query until the data returned is in line with your exact requirements.

Each query made will result in a response that clearly defines if it was successful or not. The <Response> element (or its equivalent for non-XML formats) contains this information, and if the query was successful this element will appear as follows:

<SiteConfidenceApi Version="current">
<Request/>
<Response Status="Ok" Code="200" Message="Success.">
</Response>
</SiteConfidenceApi>

Should the query fail for some reason, then one of the following errors will be reported:

Error Code Message Meaning
101 (HTTP) Service currently unavailable. The API is down or unreachable.
301 
(in the response)
Maximum number of items exceeded. Response was truncated. You have requested too much data for the API to provide in one query.
Narrow down your query, or divide it into several queries.
401 (in the response) Authentication failure. Your API key has expired.
Log in again to generate a new one.
402 (in the response) You have exceeded the maximum number of allowed requests. The number of API queries made by your company has exceeded the contractual allowance, or the allowance has not been set.
Contact Customer Support or your Account Manager.

This table is also included in Appendix D, a consolidated Troubleshooting guide that covers typical issues that you might encounter with the API user interface or when programmatically calling the API. 

6. Example Queries

To illustrate how the API might be used, here is a selection of examples showing sample goals, their required query strings and their resultant responses. In all cases the elements of the query string that are variable are highlighted in red. Feel free to copy the query string, amend these variable elements to match your own circumstances and then run the query on your own account.

6.1      How do I view the current status of a page monitor and the result status of each of its tests for today?

Test Filters

–    Select account ID
–    Select page monitor
–    Set StartDate to today
–    Set StartTime to 00:00:00
–    Set EndTime to ‘Now’ using the button on the pop-up time picker

Data Filters

–    Under Account > Pages > Page
select Url, Label, CurrentStatus, ResultCode
–    Under Account > Pages > Page > TestResults > TestResult
select LocalDateTime, Status, ResultCode

Query String (generated by the Query Builder)

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Return/[Account[Pages[Page[Url,Label,CurrentStatus,ResultCode,TestResults[TestResult[LocalDateTime,Status,ResultCode]]]]]]/AccountId/MN1A8878/Id/MN1PG43413/StartDate/2014-05-25/StartTime/00:00:00/EndTime/11:49:33/

Response (in XML format)

<SiteConfidenceApi Version="current">
<Request Return="[Account[Pages[Page[Url,Label,CurrentStatus,ResultCode,TestResults[TestResult[LocalDateTime,Status,ResultCode]]]]]]" AccountId="MN1A8878" Id="MN1PG43413" StartDate="2014-05-25" StartTime="00:00:00" EndTime="11:49:33" />
<Response Status="Ok" Code="200" Message="Success."> <Account>
<Pages>
<Page Url="http://www.bbc.co.uk/sport/0/football/" Label="BBC Football Home Page S1" CurrentStatus="OK" ResultCode="1">
<TestResults>
<TestResult LocalDateTime="2014-05-25 00:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 01:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 02:33:40" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 03:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 04:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 05:33:40" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 06:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 07:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 08:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 09:33:40" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 10:33:39" Status="OK" ResultCode="1"/>
<TestResult LocalDateTime="2014-05-25 11:33:39" Status="OK" ResultCode="1"/>
</TestResults>
</Page>
</Pages>
</Account>
</Response>
</SiteConfidenceApi>

Click  to download a video of this example (there may be a short delay in this loading).

This shows that there have been 12 tests run so far today and that all of those completed successfully without warnings (status OK, result code 1).

Note that test results are displayed in chronological order, with the oldest results displayed first.

6.2      How do I view the average speed of a user journey and also of its individual steps over the last 7 days?

Test Filters

–    Select account ID
–    Select user journey (which automatically selects all the steps as well)

Data Filters

–    Under Account > UserJourneys > UserJourney
select Label
–    Under Account > UserJourneys > UserJourney > TestingSummary > Last7Days
select AverageDownloadSpeed
–    Under Account > UserJourneys > UserJourney > Steps > Step
select Label
–    Under Account > UserJourneys > UserJourney > Steps > Step > TestingSummary > Last7Days
select AverageDownloadSpeed

Query String (generated by the Query Builder)

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Return/[Account[UserJourneys[UserJourney[Label,TestingSummary[Last7Days[AverageDownloadSpeed]],Steps[Step[Label,TestingSummary[Last7Days[AverageDownloadSpeed]]]]]]]]/AccountId/MN1A8878/Id/MN1UJ4065,MN1UJ4065S50760,MN1UJ4065S50761,MN1UJ4065S50762,MN1UJ4065S50763,MN1UJ4065S50764,MN1UJ4065S51246,MN1UJ4065S51824/

Response (in XML format)

<SiteConfidenceApi Version="current">
<Request Return=" [Account[UserJourneys[UserJourney[Label,TestingSummary[Last7Days[AverageDownloadSpeed]],Steps[Step[Label,TestingSummary[Last7Days[AverageDownloadSpeed]]]]]]]]" AccountId="MN1A8878" Id="MN1UJ4065,MN1UJ4065S50760,MN1UJ4065S50761,MN1UJ4065S50762,MN1UJ4065S50763,MN1UJ4065S50764,MN1UJ4065S51246,MN1UJ4065S51824"/><Response Status="Ok" Code="200" Message="Success.">
<Account>
<UserJourneys>
<UserJourney Label="Test Journey">
<TestingSummary>
<Last7Days AverageDownloadSpeed="5.1024286"/>
</TestingSummary>
<Steps>
<Step Label="Step 1">
<TestingSummary>
<Last7Days AverageDownloadSpeed="2.8974286"/>
</TestingSummary>
</Step>
<Step Label="Step 2">
<TestingSummary>
<Last7Days AverageDownloadSpeed="0.7018571"/>
</TestingSummary>

</Step>

…
</Steps>
</UserJourney>
</UserJourneys>
</Account>
</Response>
</SiteConfidenceApi>

This shows that the average download speed of the journey over the last 7 days was 5.10 seconds and that the average download speed of the first two steps (others have been omitted for conciseness) is 2.89 seconds and 0.70 seconds respectively.

6.3      How do I view the uptime of a page monitor for the previous calendar month?

Test Filters

–    Select account ID
–    Select page monitor
–    Set StartDate to 1st of previous calendar month
–    Set StartTime to 00:00:00
–    Set EndDate to last day of previous calendar month
–    Set EndTime to 23:59:59

Data Filters

–    Under Account > Pages > Page
select Url, Label
–    Under Account > Pages > Page > AvailabilitySummary > Availability
select Time
–    Under Account > Pages > Page > AvailabilitySummary > Availability > Uptime
select Percentage, Time
–    Under Account > Pages > Page > AvailabilitySummary > Availability > Warning
select Percentage, Time
–    Under Account > Pages > Page > AvailabilitySummary > Availability > Problem
select Percentage, Time
–    Under Account > Pages > Page > AvailabilitySummary > Availability > Down
select Percentage, Time

Query String (generated by the Query Builder)

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Return/[Account[Pages[Page[Url,Label,AvailabilitySummary[Availability[Time,Uptime[Percentage,Time],Warning[Percentage,Time],Problem[Percentage,Time],Down[Percentage,Time]]]]]]]/AccountId/MN1A8878/Id/MN1PG50365/StartDate/2014-04-01/StartTime/00:00:00/EndDate/2014-04-30/EndTime/23:59:59/

Response (in XML format)

<SiteConfidenceApi Version="current">
 <Request Return="[Account[Pages[Page[Url,Label,AvailabilitySummary[Availability[Time,Uptime[Percentage,Time],Warning[Percentage,Time],Problem[Percentage,Time],Down[Percentage,Time]]]]]]]" AccountId="MN1A8878" Id="MN1PG50365" StartDate="2014-04-01" StartTime="00:00:00" EndDate="2014-04-30" EndTime="23:59:59"/>
<Response Status="Ok" Code="200" Message="Success."><Account>
<Pages>
<Page Url="http://www.o2.co.uk/login" Label="http://www.o2.co.uk/login"><AvailabilitySummary>
<Availability Time="2592000"><Uptime Percentage="99.106211419753" Time="2568833"/>
<Warning Percentage="0.13846450617284" Time="3589"/>
<Problem Percentage="0" Time="0"/>
<Down Percentage="0.75532407407407" Time="19578"/>
</Availability>
</AvailabilitySummary>
</Page>
</Pages>
</Account>
 </Response>
 </SiteConfidenceApi>

This shows that during the previous calendar month the uptime percentage for the monitor was 99.10%. This is the time that the monitor was up (2,568,833 seconds) expressed as a percentage of the total time period for the previous calendar month (2,592,000 seconds). Similarly, the monitor was in a confirmed Warning status for 0.14% of the month, a confirmed Problem status for 0% of the month and a confirmed Down status for 0.76% of the month.

6.4      How do I view the outcome of the last test of a page monitor, including the time and speed of that test?

Test Filters

–    Select account ID
–    Select page monitor

Data Filters

–    Under Account > Pages > Page
select Url, Label, LastTestLocalDateTime, LastTestDownloadSpeed, CurrentStatus, ResultCode

Query String (generated by the Query Builder)

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Return/[Account[Pages[Page[Url,Label,LastTestLocalDateTime,LastTestDownloadSpeed,CurrentStatus,ResultCode]]]]/AccountId/MN1A8878/Id/MN1PG43413/

Response (in XML format)

<SiteConfidenceApi Version="current">
 <Request Return=" [Account[Pages[Page[Url,Label,LastTestLocalDateTime,LastTestDownloadSpeed,CurrentStatus,ResultCode]]]]" AccountId="MN1A8878" Id="MN1PG43413”/>
<Response Status="Ok" Code="200" Message="Success.">
<Account>
<Pages>
<Page Url="http://www.bbc.co.uk/sport/0/football/" Label="BBC Football Home Page S1 " LastTestLocalDateTime="2014-05-25 11:33:39" LastTestDownloadSpeed="4.809" CurrentStatus="OK" ResultCode="1"/>
</Page>
</Pages>
</Account>
 </Response>
 </SiteConfidenceApi>

So, for example, this shows that the last test was run on 25/05/2014 at 11:33:39 and that it completed successfully without warnings (status OK, result code 1) with a download time of 4.809 seconds.

6.5      How do I view the DNS Resolution Time, Connect Time, Data Start Time and Overall Download Time for today’s tests of a page monitor?

Test Filters

–    Select account ID
–    Select page monitor
–    Set StartDate to today
–    Set StartTime to 00:00:00
–    Set EndTime to ‘Now’ using the button on the pop-up time picker

Data Filters

–    Under Account > Pages > Page
select Url, Label
–    Under Account > Pages > Page > TestResults > TestResult
select LocalDateTime, DnsSeconds, ConnectSeconds, DataStartSeconds, TotalSeconds

Query String (generated by the Query Builder)

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Return/[Account[Pages[Page[Url,Label,TestResults[TestResult[LocalDateTime,DnsSeconds,ConnectSeconds,DataStartSeconds,TotalSeconds]]]]]]/AccountId/MN1A8878/Id/MN1PG43413/StartDate/2014-05-25/StartTime/00:00:00/EndTime/11:50:23

Response (in XML format)

<SiteConfidenceApi Version="current">
 <Request Return=" [Account[Pages[Page[Url,Label,TestResults[TestResult[LocalDateTime,DnsSeconds,ConnectSeconds,DataStartSeconds,TotalSeconds]]]]]]" AccountId="MN1A8878" Id="MN1PG43413" StartDate="2014-05-25" StartTime="00:00:00" EndTime="11:50:23"/>
<Response Status="Ok" Code="200" Message="Success.">
<Account>
<Pages>
<Page Url="http://www.bbc.co.uk/sport/0/football/" Label="BBC Football Home Page S1">
<TestResults>
<TestResult LocalDateTime="2014-05-25 00:33:40" DnsSeconds="0.001" ConnectSeconds="0.002" DataStartSeconds="0.004" TotalSeconds="4.775"/>
<TestResult LocalDateTime="2014-05-25 01:33:39" DnsSeconds="0.001" ConnectSeconds="0" DataStartSeconds="0.074" TotalSeconds="4.916"/>
<TestResult LocalDateTime="2014-05-25 02:33:39" DnsSeconds="0.004" ConnectSeconds="0.002" DataStartSeconds="0.002" TotalSeconds="4.832"/>
<TestResult LocalDateTime="2014-05-25 03:33:39" DnsSeconds="0.001" ConnectSeconds="0.001" DataStartSeconds="0.006" TotalSeconds="6.635"/>
<TestResult LocalDateTime="2014-05-25 04:33:39" DnsSeconds="0.008" ConnectSeconds="0.002" DataStartSeconds="0.005" TotalSeconds="4.76"/>
<TestResult LocalDateTime="2014-05-25 05:33:39" DnsSeconds="0.006" ConnectSeconds="0.002" DataStartSeconds="0.08" TotalSeconds="4.776"/>
<TestResult LocalDateTime="2014-05-25 06:33:39" DnsSeconds="0.001" ConnectSeconds="0.001" DataStartSeconds="0.004" TotalSeconds="4.798"/>
<TestResult LocalDateTime="2014-05-25 07:33:40" DnsSeconds="0.002" ConnectSeconds="0.002" DataStartSeconds="0.086" TotalSeconds="4.723"/>
<TestResult LocalDateTime="2014-05-25 08:33:39" DnsSeconds="0.001" ConnectSeconds="0.001" DataStartSeconds="0.002" TotalSeconds="5.178"/>
<TestResult LocalDateTime="2014-05-25 09:33:40" DnsSeconds="0" ConnectSeconds="0.001" DataStartSeconds="0.002" TotalSeconds="4.753"/>
<TestResult LocalDateTime="2014-05-25 10:33:40" DnsSeconds="0" ConnectSeconds="0.002" DataStartSeconds="0.004" TotalSeconds="4.682"/>
<TestResult LocalDateTime="2014-05-25 11:33:39" DnsSeconds="0.002" ConnectSeconds="0.001" DataStartSeconds="0.003" TotalSeconds="4.809"/> </TestResults>
</Page>
</Pages>
</Account>
 </Response>
 </SiteConfidenceApi>

So, for example, this shows that the first test run today reported the following timings breakdown:

DNS Resolution Time    :    0.001 seconds
Connection Time           :    0.002 seconds
Data Start Time             :    0.004 seconds
Overall Download Time :    4.775 seconds

6.6      How do I view all the components that were downloaded by a particular test or group of tests of a page monitor, and the download time for each component?

Test Filters

–    Select account ID
–    Select page monitor
–    Set StartDate, Start Time, EndDate and EndDate so that the time range spans the relevant test(s)

Data Filters

–    Under Account > Pages > Page
select Url, Label
–    Under Account > Pages > Page > TestResults > TestResult
select LocalDateTime
–    Under Account > Pages > Page > TestResults > TestResult > TestResultDetails > ResultDetail
select ObjectUrl, TotalSeconds

Query String (generated by the Query Builder)

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Return/[Account[Pages[Page[Url,Label,TestResults[TestResult[LocalDateTime,TestResultDetails[ResultDetail[ObjectUrl,TotalSeconds]]]]]]]]/AccountId/MN1A8878/Id/MN1PG43413/StartDate/2014-05-25/StartTime/10:52:00/EndTime/11:52:23/

Response (in XML format)

<SiteConfidenceApi Version="current">
 <Request Return=" [Account[Pages[Page[Url,Label,TestResults[TestResult[LocalDateTime,TestResultDetails[ResultDetail[ObjectUrl,TotalSeconds]]]]]]]]" AccountId="MN1A8878" Id="MN1PG43413" StartDate="2014-05-25" StartTime="10:52:00" EndTime="11:52:23"/>
<Response Status="Ok" Code="200" Message="Success.">
<Account>
<Pages>
<Page Url="http://www.bbc.co.uk/sport/0/football/" Label="BBC Football Home Page S1">
<TestResults><TestResult LocalDateTime="2014-05-25 11:33:39">
<TestResultDetails>
<ResultDetail ObjectUrl="http://www.bbc.co.uk/sport/0/football/" TotalSeconds="0.417"/>
<ResultDetail ObjectUrl="https://static.bbci.co.uk/frameworks/pulsesurvey/0.10.2/style/pulse.css" TotalSeconds="0.108"/>
<ResultDetail ObjectUrl="http://feeds.bbci.co.uk/modules/comments/getcount/?items=__CPS_27559180" TotalSeconds="0.109"/>
<ResultDetail ObjectUrl="https://news.bbcimg.co.uk/js/config/apps/4_7_2/bbc_fmtj_config.js" TotalSeconds="0.11"/>
<ResultDetail ObjectUrl="https://static.bbci.co.uk/sport/ui/3.2.172/css/desktop/elements/branding/olympics-2012.css" TotalSeconds="0.111"/>
…
<ResultDetail ObjectUrl="https://news.bbcimg.co.uk/media/images/75052000/jpg/_75052634_v1play.jpg" TotalSeconds="0.203"/>
</TestResultDetails>
</TestResult>
</TestResults>
</Page>
</Pages>
</Account>
 </Response>
 </SiteConfidenceApi>

This example covers just a single test and for that test shows that the first object downloaded (the root component for the page test) was http://www.bbc.co.uk/sport/0/football/ and took 0.417 seconds to download and that the last component was an image file located at https://news.bbcimg.co.uk/media/images/75052000/jpg/_75052634_v1play.jpg and this took 0.203 seconds to download.

NOTE: This type of query generates a lot of data for each test so always try to be as specific as you can when defining the tests to be covered by setting your test filters as narrowly as possible.

6.7      How do I check the monitoring status of all my page monitors and user journeys, and also the alerting status of the page monitors and of the individual steps of user journeys?

Test Filters

–    Select account ID
–    Select each monitor (for user journeys all the steps are then automatically selected as well)

Data Filters

–    Under Account > Pages > Page
select Url, Label, Monitoring, Alerting
–    Under Account > UserJourneys > UserJourney
select Label, Monitoring
–    Under Account > UserJourneys > UserJourney > Steps > Step
select Label, Monitoring, Alerting

Query String (generated by the Query Builder)

https://api.siteconfidence.co.uk/current/abcdefghijklmnopqrstuvwxyz123456/Return/[Account[Pages[Page[Url,Label,Monitoring,Alerting]],UserJourneys[UserJourney[Label,Monitoring,Steps[Step[Label,Monitoring,Alerting]]]]]]/AccountId/MN1A8878/Id/MN1PG43413,MN1UJ4065,MN1UJ4065S50760,MN1UJ4065S50761,MN1UJ4065S50762,MN1UJ4065S50763,MN1UJ4065S50764,MN1UJ4065S51246,MN1UJ4065S51824/

Response (in XML format)

<SiteConfidenceApi Version="current">
 <Request Return=" [Account[Pages[Page[Url,Label,Monitoring,Alerting]],UserJourneys[UserJourney[Label,Monitoring,Steps[Step[Label,Monitoring,Alerting]]]]]]" AccountId="MN1A8878" Id="MN1PG43413,MN1UJ4065,MN1UJ4065S50760,MN1UJ4065S50761,MN1UJ4065S50762,MN1UJ4065S50763,MN1UJ4065S50764,MN1UJ4065S51246,MN1UJ4065S51824"/>
<Response Status="Ok" Code="200" Message="Success."><Account>
<Pages>
<Page Url="http://www.bbc.co.uk/sport/0/football/" Label="BBC Football Home Page S1" Monitoring="true" Alerting="true"/>
</Pages>
<UserJourneys>
<UserJourney Label="Test Journey" Monitoring="true">
<Steps>
<Step Label="Step 1" Monitoring="true" Alerting="false"/>
<Step Label="Step 2" Monitoring="true" Alerting="false"/>
<Step Label="Step 3" Monitoring="true" Alerting="false"/>
<Step Label="Step 4" Monitoring="true" Alerting="false"/>
<Step Label="Step 5" Monitoring="true" Alerting="false"/>
<Step Label="Step 6" Monitoring="false" Alerting="false"/>
<Step Label="Step 7" Monitoring="false" Alerting="false"/>
</Steps>
</UserJourney>
</UserJourneys>
</Account>
</Response>
</SiteConfidenceApi>

This shows that for this account there is one page monitor and one user journey. The page monitor has monitoring enabled and alerting enabled. For the user journey, monitoring is enabled although steps 6 and 7 are disabled, and alerting is disabled on all steps.

7. Using Your Query

If you just intend to use your query manually from time to time, then it can be re-run at any time as follows:

  • Log into the API user interface to generate a new API key
  • Replace the existing API key in your query with the new key
  • Change any other variable elements of the query (such as dates) as required
  • Resubmit the revised query URL via your browser

The majority of API usage, however, is via purpose-built applications. The key points when building such applications are:

  • Allow for the need to generate a new API key
    If the interval between your queries will exceed 59 minutes, then the application must generate a new API key on each use. However, even if this is not the case, we still recommend that you incorporate functionality to create a new key automatically if the response indicates an authentication failure (see next section for more details of this error message). To generate a new key programmatically, you simply append the appropriate username and password to the API URL as shown below and submit this request (substituting the values highlighted in red appropriately):

https://api.siteconfidence.co.uk/current/username/me@my.com/password/mypassword

This will generate a response of the following format that shows the new API key (highlighted below in green):

<SiteConfidenceApi Version="current">
<Request/>
<Response Status="Ok" Code="200" Message="Success.">
<ApiKey Lifetime="3600">abcdefghijklmnopqrstuvwxyz123456</ApiKey>
</Response>
</SiteConfidenceApi>
  • Any error messages returned by the API should be handled
    Ideally, errors should be handled in way that notifies interested parties of a problem in a timely manner and that provides a clear and meaningful explanation of the problem where possible. As previously mentioned in the ‘Response’ section earlier in this document, each query made will result in a response that clearly defines if it was successful or not. The <Response> element (or its equivalent for non-XML formats) contains this information, and if the query was successful this element will appear as follows:
<SiteConfidenceApi Version="current">
<Request/>
<Response Status="Ok" Code="200" Message="Success.">
</Response>
</SiteConfidenceApi>

Should the query fail for some reason, one of a number of HTTP errors will be reported. These are essentially the same as those covered in the ‘Response’ section of this document for manual users of the API user interface but also include certain scenarios that might arise due to a programmatic error with the query:

Error Code Message Meaning
101
(HTTP)
Service currently unavailable. The API is down or unreachable.
301
(in the response)
Maximum number of items exceeded. Response was truncated. You have requested too much data for the API to provide in one query.
401
(in the response)
Authentication failure. This could be due to one of several reasons:

  • The API key has expired, in which case generate a new one and incorporate this into your query.
  • The application has provided an incorrect API key (though of the correct length of 32 characters).
  • The account you are using does not have access to the API. Contact your Account Manager.
402
(in the response)
You have exceeded the maximum number of allowed requests. The number of API queries made by your company has exceeded the contractual allowance.
Contact Customer Support or your Account Manager.
402
(HTTP)
Payment Required. The number of API queries made by your company has exceeded the contractual allowance.Contact Customer Support or your Account Manager.
404
(HTTP)
Not Found. The API cannot resolve the supplied query URL.
Most likely the URL has been constructed incorrectly, for example an API key of a length other than 32 characters has been used.

This table is also included in Appendix D, a consolidated Troubleshooting guide that covers typical issues that you might encounter with the API user interface or when programmatically calling the API.

  • Make use of the available choices for formatting the response
    The API allows you to specify certain formats for the returned data. You can choose from XML, JSON, PHP or YAML. The default is XML, but if you require the response to be in one of the other formats then you can specify that format by appending /Format/xxxx to your query, where xxxx represents the required format. For example, to format the response as JSON you would submit a query of the form:
https://api.siteconfidence.co.uk/current/.../Format/json
  • Consider the most appropriate way to use the data
    Typically, our customers further filter the data from our API according to their specific business needs and then pass it in a suitably translated form to some type of off-the-shelf real-time reporting/graphical software such as Splunk or Graphite. Occasionally just exporting the filtered data to a spreadsheet is sufficient. Rarely is there the need to build a bespoke graphical/presentation layer.

As mentioned at the start of this guide, Appendix A contains some examples of how our API has been used.

Appendix A – Examples of API Implementations

A.1      NCC Group Interactive Dashboard

NCC Group has built an Interactive Dashboard product that represents its own implementation of the API.

The Interactive Dashboard provides a real-time view of the performance and availability of a customer’s websites. It is a customisable front-end that complements our existing Monitoring product and displays up to 40 active monitors to give a rich, consolidated view of the health of your sites by providing a clear overview of the status of key monitors and allowing users to drill down into specific test results.

The image below shows an example of the dashboard. The rows represent individual monitors and the different colours of the bar for that monitor represent their status as time passes. The lines embedded within each bar also provide an indication of response time for the monitor, and the latest response time is displayed to the right of the bar. Clicking within a bar will also take you to the related test results that underlie that area of the bar.

api7

A.2      Comparison of current performance against historical performance

This implementation by one of our customers provides a dashboard that graphically compares the current Data Start and Total Download times for their monitors against those same timings from exactly one week ago. This allows any patterns in performance to be easily identified (e.g. times of the day or days of the week when site response is particularly slow) and also enables any deviations from an established pattern (such as higher response times than usual) to be quickly recognised and investigated.

The screenshot below shows how the dashboard has been divided into four areas that show Data Start time (referred to as ‘Time to first byte’) and Total Download time for page monitors and user journeys. Solid lines within graphs represent the current metrics, whereas dotted lines represent those from one week ago.

api8

Appendix B – Query Builder Screen

api9

Appendix C – Query Builder Arguments Screen

api10

Appendix D – Troubleshooting Guide

This Troubleshooting guide is intended to be an initial point of quick reference to assist you in understanding and, if possible, resolving typical issues that you might encounter when using the API.

User Interface

General Issues

Issue Meaning
Authentication failure.’ message displayed when trying to log in. The account you are using does not have access to the API.
Contact your Account Manager.
You have exceeded the maximum number of allowed requests.’ message displayed when trying to log in. The number of API queries made by your company has exceeded the contractual allowance, or the allowance has not been set.Contact Customer Support or your Account Manager.
Query Builder ‘AccountId’ filter does not offer all the monitoring accounts you expect. The account you are using does not have access to all required monitoring accounts.
Contact Customer Support or your Account Manager.
Query Builder ‘Id’ filter drop-down is empty. This could be due to one of two reasons:

  • You have not selected any accounts from the AccountId drop-down.
    Go back and select at least one AccountId.
  • If this is the first time you are using the API user interface then it may be that an API query allowance has not been set for your company. To verify this, please exit the API and try to log in again.
Query Builder Return tree does not contain a branch that you expect. None of the tests covered by the test filters you have defined contain any data within this branch of the Return tree.
Your query returns results for significantly fewer tests than you expected. The LimitTestResults value may not have been defined, in which case only 20 test results will be returned.
Increase the LimitTestResults value as necessary.
Query Builder becomes unresponsive when trying to select test filters or data filters. Your API key may have expired.
Try refreshing the screen (F5) to see if a 401 authentication failure message is displayed. If so, then the key has indeed expired, in which case you will need to log into the API again to generate a new one.

Specific Error Codes

Error Code Message Meaning
101
(HTTP)
Service currently unavailable. The API is down or unreachable.
301
(in the response)
Maximum number of items exceeded. Response was truncated. You have requested too much data for the API to provide in one query.
Narrow down your query, or divide it into several queries.
401
(in the response)
Authentication failure. Your API key has expired.
Log in again to generate a new one.
402
(in the response)
You have exceeded the maximum number of allowed requests. The number of API queries made by your company has exceeded the contractual allowance, or the allowance has not been set.
Contact Customer Support or your Account Manager.

Programmatic Calls

Error Code Message Meaning
101
(HTTP)
Service currently unavailable. The API is down or unreachable.
Contact Customer Support
301
(in the response)
Maximum number of items exceeded. Response was truncated. You have requested too much data for the API to provide in one query.
Narrow down your query, or divide it into several queries.
401
(in the response)
Authentication failure. This could be due to one of several reasons:

  • The API key has expired, in which case generate a new one and incorporate this into your query.
  • The application has provided an incorrect API key (though of the correct length of 32 characters).
  • The account you are using does not have access to the API. Contact your Account Manager.
402
(in the response)
You have exceeded the maximum number of allowed requests. The number of API queries made by your company has exceeded the contractual allowance.
Contact Customer Support or your Account Manager.
402
(HTTP)
Payment Required, The number of API queries made by your company has exceeded the contractual allowance.Contact Customer Support or your Account Manager.
404
(HTTP)
Not Found, The API cannot resolve the supplied query URL.
Most likely the URL has been constructed incorrectly, for example an API key of a length other than 32 characters has been used.

Leave a Reply

Your email address will not be published. Required fields are marked *