← Back to Service Diagnostic Tests

Introduction

Use these endpoints to run a diagnostic test on a service.

Request Lifecycle

Running a diagnostic test is a two step process as follows:

  1. Create a request, by sending a POST request to /api/connect/services/diagnostic-tests/request with the body of the request containing the service id, and the diagnostic test. The response’s http status will be 201 with a blank response body. There will be a Location response header with a URL. This URL is where the request outcome can be obtained.

  2. Make a GET request to the URL returned in 1. to retrieve the outcome of the diagnostic test. While the test is in progress, the response’s http status will be 202. When the test has completed, a 200 is returned, with the results in the body. If the test could not be completed, a 422 will be returned, with the body containing details on why it failed in the standard error format.

Request Specifications

Table 1. API Versions
Version Header Changes

1 (Deprecated)

X-API-VERSION=1

Initial Version

2 (Deprecated)

X-API-VERSION=2

No change

3

X-API-VERSION=3

No change

4

X-API-VERSION=4

No change

5

X-API-VERSION=5

No change

6

X-API-VERSION=6

No Change

7

X-API-VERSION=7

No Change

API Version 1, 2, 3, 4, 5, 6 and 7

POST Request

Table 2. POST Request

Verb

POST

URI

/api/connect/services/diagnostic-tests/request
Table 3. POST HTTP Request Headers
Name Description

Authorization

The OAuth bearer access token

X-API-VERSION

The version of the endpoint you are accessing
Table 4. POST Request Body Fields
Path Type Description Required

serviceId

Number

The id of the service.

Required

testType

String

The diagnostic test.

Required

POST Response

Table 5. POST HTTP Status Codes
Status Code Meaning

201

The request was created successfully

401

Bearer token is missing or invalid

404

You do not have permission to perform this task or The id of the service resource provided does not exist

422

There are validation errors on the request you made. Check the response body to see what fields had issues.

500

There was an unexpected error processing the request

502

There was an unexpected error with one or more of the upstream services
Table 6. POST HTTP Response Headers
Name Description

Location

The URL to check the outcome of the diagnostic test request

GET Request

Note
 The URI will be given to you in the Location header of the POST request of the Service Diagnostic Test request.
Table 7. GET Request

Verb

GET

URI

/api/connect/services/diagnostic-tests/requests/{id}
Table 8. GET Request Path Variables

Path Variable

Purpose

id

The id to poll to check the outcome of the diagnostic test request
Table 9. GET HTTP Request Headers
Name Description

Authorization

The OAuth bearer access token

X-API-VERSION

The version of the endpoint you are accessing

GET Response

Table 10. GET HTTP Status Codes
Status Code Meaning

200

The request is complete. The body contains the result of the diagnostic test

202

The request is in progress

401

Bearer token is missing or invalid

404

You do not have permission to perform this task or The id of the diagnostic-test-request resource provided does not exist

422

The test did not complete. Check the response body to see why

500

There was an unexpected error processing the request
Table 11. GET Response Body Fields
Path Type Description

serviceId

Number

service id

testType

String

diagnostic test

createdOn

String

requested on

result

Object

diagnostic test result

result.status

Array

result.status.[].name

String

Status name

result.status.[].reason

String

result.status.[].created_at

String

When status was entered.

result.type

String

diagnostic test

result.result

Object

Results of the diagnostic test. Varies depending on type of test.

result.is_active

Boolean

Indicates whether the test is in a finalised state.

result.requested_at

String

More details on the different test results can be found here.

API Version 1, 2, 3, 4, 5, 6 and 7 - Examples

Successful Request

A service diagnostic test request is created by sending a POST request to /api/connect/services/diagnostic-tests/request.

POST Request
POST /api/connect/services/diagnostic-tests/request HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Content-Length: 54
Host: 360-api.superloop.com

{
  "serviceId" : 12345,
  "testType" : "port-reset"
}

If all required fields were given, then the response to the request will have:

  1. a http status of 201

  2. a Location header with the URI to check the diagnostic test result.

Successful POST Response
HTTP/1.1 201 Created
Location: /api/connect/services/diagnostic-tests/requests/557
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Once you have the URI from the Location header, poll that URI every so often by making a GET request. While the diagnostic test is in progress, the GET request’s response will have a http status of 202. Keep polling the URL until it finishes. Once the test has completed successfully, the GET request’s response will have a http status of 200 and the body of the response will contain the result.

Note
 Please keep the polling to a sensible rate.
GET Request
GET /api/connect/services/diagnostic-tests/requests/557 HTTP/1.1
Content-Type: application/json;charset=UTF-8
Authorization: Bearer **token**
X-API-VERSION: 7
Host: 360-api.superloop.com
Successful GET Response
HTTP/1.1 200 OK
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 857

{
  "serviceId" : 12345,
  "testType" : "port-reset",
  "createdOn" : "2025-03-11T22:28:04Z",
  "result" : {
    "id" : "67d802c5-e7d3-42ff-b827-2d1e889a1183",
    "status" : [ {
      "name" : "completed",
      "reason" : null,
      "created_at" : "2020-12-14 09:08:30"
    }, {
      "name" : "accepted",
      "reason" : null,
      "created_at" : "2020-12-14 09:08:27"
    }, {
      "name" : "in-progress",
      "reason" : null,
      "created_at" : "2020-12-14 09:08:27"
    }, {
      "name" : "pending",
      "reason" : null,
      "created_at" : "2020-12-14 09:08:18"
    } ],
    "type" : "port-reset",
    "result" : {
      "nbn_test_id" : "WRI904950000000",
      "result" : "Passed",
      "start" : "2020-12-14 09:08:23",
      "end" : "2020-12-14 09:08:27"
    },
    "is_active" : false,
    "requested_at" : "2020-12-14 09:08:18"
  }
}

Diagnostic Test In Progress

While the diagnostic test is in progress, a http status of 202 is returned.

Diagnostic Test In Progress GET Response
HTTP/1.1 202 Accepted
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY

Diagnostic Test Did Not Complete

If the diagnostic test could not be completed, a http status of 422 is returned and the body of the response will list the problem.

This example is of a service diagnostic test request that timed out.

Diagnostic Test Timed Out GET Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 442

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.service-diagnostic-test-request.timed-out",
    "message" : "The Service Diagnostic Test Request has timed out",
    "object" : "ServiceDiagnosticTestResource",
    "field" : "status",
    "rejectedValue" : "TIMEOUT"
  } ],
  "timestamp" : "2025-03-11T22:28:06.175526248Z"
}

This example is of a service diagnostic test request that has an error.

Diagnostic Test Error GET Response
HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 444

{
  "httpStatusCode" : 422,
  "type" : "client.validation",
  "code" : "validation",
  "message" : "Validation error",
  "apiSubErrors" : [ {
    "code" : "constraints.service-diagnostic-test-request.in-error",
    "message" : "The Service Diagnostic Test Request has errored",
    "object" : "ServiceDiagnosticTestResource",
    "field" : "status",
    "rejectedValue" : "ERROR_OCCURRED"
  } ],
  "timestamp" : "2025-03-11T22:28:02.6885025Z"
}

Upstream Service Unavailable

If one of the services that Connect API uses for running diagnostic tests is down or unreachable, Connect API will return a http status of 502.

Upstream Service Unavailable POST Response
HTTP/1.1 502 Bad Gateway
Content-Type: application/json
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
Cache-Control: no-cache, no-store, max-age=0, must-revalidate
Pragma: no-cache
Expires: 0
X-Frame-Options: DENY
Content-Length: 249

{
  "httpStatusCode" : 502,
  "type" : "remote.call",
  "code" : "remote.call.error",
  "message" : "There was an unexpected error with one or more of the upstream services",
  "apiSubErrors" : [ ],
  "timestamp" : "2025-03-11T22:28:03.813959539Z"
}