Introduction

OPX-RTU HTTP API provides a way to control an OPX-RTU device and get information about it’s state. It can be used in any programming language that supports sending HTTP requests and receiving HTTP responses. The API is already used by the OPX-RTU web user interface, which is available to the user by pointing his browser to the OPX-RTU’s IP address.

General API Concepts

The OPX-RTU API is resource-oriented, which means that every controllable RTU aspect is exposed as a resource. This is similar to the REST (Representational State Transfer) architecture style, although the OPX-RTU API may not conform to all the RESTful constraints completely.

Resource URL

Each API resource is accessible through it’s own URL. All the URLs start with the following base part:

http://rtu-address/api/v1

where

http

stays for HTTP protocol;
rtu-address

either IP or domain address of an RTU;
v1

stays for the version 1 of the API, described in this document.

This base part is assumed and will be omitted in the API URLs below in this document for brevity. E.g., the URL /monitoring/tests/abc will actually mean http://rtu-address/api/v1/monitoring/tests/abc.

Request Methods

Currently, the following HTTP methods are used in the API:

OPTIONS

is used to get all the methods supported by an API resource URL;
GET

is used to get an API resource representation;
POST

is used to add a resource to a parent resource collection;
PATCH

is used to partially change a resource, i.e. some of it’s properties;
DELETE

is used to remove a resource.

Resource Representation Format

Most resources are lists (sometimes nested) of key-value pairs. JSON representation is used for such resources. JSON representation of a resource may be also called JSON object in this document. Also, name/value pairs of a JSON object will be called properties.

MIME-type for JSON representation is application/json.

Properties names and descriptions of resource’s JSON representation will be described like this:

"name"

description.

Resources representations in the document below are defined by their MIME-types.

Partial Resource Representation

When the client needs to update some of the resource’s properties, it issues a PATCH request with the JSON Merge Patch content. The content object has the resource’s properties, which needs to be updated.

MIME-type for JSON Merge Patch representation is application/merge-patch+json.

Important
 Some of the resources allow to change only a single property at a time. Sending the JSON Merge Patch object with multiple properties to such resources will result in the 400 Bad Request response.

Collection Resources

If a resource is a collection of child resources, it’s JSON has the following properties:

"items"

an array of child resources, which are included in this representation;
"offset"

an integer, an index in the whole collection of the first child resource included in this representation;
"total"

an integer, a total number of child resources in the whole collection.

Such collection resource representation may contain only a part of the whole collection (see Pagination).

Binary Resources

Some resources (e.g., SOR-traces) are binary data. These resources can be represented both in binary form or in JSON format. Binary representation has MIME-type application/octet-stream. JSON representation of such a resource has the following properties:

"data"

a string, containing the encoded resource data;
"encoding"

a string, name of encoding method; currently the only value of "base64" is supported for the Base64 encoding.

When binary resources are uploaded to the server, they are expected to be in the Multipart Form Data format with MIME-type of multipart/form-data.

Collections Of Binary Resources

A resource which is a collection of binary sub-resources may be represented in JSON as a general collection (as described in Collection Resources). Also, such resource may be represented as a whole in a binary form (as described in Binary Resources), which is a ZIP file containing all the binary sub-resources.

When multiple binary representation are uploaded to the server, they may be uploaded either as multiple entries in a Multipart Form Data request, or they can be uploaded in a ZIP file being a single entry of a Multipart Form Data request.

Other Resource Types

There may be resources of other types in the API. E.g., the Report resource may have the text/html or application/pdf MIME-type.

HTTP Headers

The MIME-type of a resource’s representation is specified in the Content-Type header, both for client requests (if the request contains the resource’s representation) and server responses (if the response contains the resource’s representation).

If a resource has multiple representations, client can choose the one it needs with the Accept request header, containing the corresponding MIME-type. If the header is missing for such a resource, then the server chooses some default resource representation format. A Report resource additionally supports selecting the representation with the extension in the filename part of URL.

When the client request results in a new resource creation in a location chosen by the server, then the location URL is reflected in the Location response header.

HTTP methods, supported by a resource, are returned in the Allow response header. This header is returned upon the OPTIONS request.

Errors

In case of an error situation an 4xx or 5xx HTTP status code is generated. Also, there may be an optional JSON object in a response body with the following member:

"message"

a string, containing an some information about the error.

Pagination

There may be situations when including the whole Collection Resource in a response is not needed or even not desirable (e.g., for efficiency reasons). In such situation a technique called pagination may be used. With this technique only a part of a collection is returned, which starts at some collection item and includes several consecutive collection items.

There are two optional query parameters which may be specified to control pagination:

offset

The zero-based starting index of the first item to return. Default value of the parameter is 0.
limit

The maximum number of collection items to return. Minimum value of the parameter is 1.
Note
 The server may return less items, then specified by the limit query parameter. If the limit query parameter is not specified, the server may return less items then the collection contains.
Note
 While pagination may be applied by the server even for an embedded collection (see, Link Expansion), there is no way for the client to provide request parameters for such an embedded collection.
Example 1. Pagination
Request
GET /monitoring/tests?offset=3&limit=5
Response
200 OK
Content-Type: application/json
{
  "items": [
    {
      "self": "tests/42761bb7-59f9-4b41-8564-e37234f26586"
    },
    {
      "self": "tests/660b7e8a-6d21-42e5-8131-d80afc1fca06"
    },
    {
      "self": "tests/7ab151a8-4629-4fb4-9f47-306605df3aaa"
    },
    {
      "self": "tests/885f4e2e-8c54-44e7-b9fa-dfe7bab20e08"
    },
    {
      "self": "tests/8a2925b6-2bad-4cfe-a3f5-46a67e4fd18e"
    }
  ],
  "offset": 3,
  "total": 11
}

Requesting Arbitrary Fields

If the client only needs some of the resource’s properties, it may tell the server which properties to include in the resource JSON representation, providing the fields query parameter. The parameter must contain a comma separated property names.

Property names may include dots to specify properties in nested objects. E.g., if a resource representation object contains a property named "child", which in turn holds an object with a property "nested", then such a property may be specified in the fields parameter as child.nested.

The client may specify some property for each collection item. E.g., if a resource representation object contains a property named "child", which in turn holds an collection of objects, each having a property "nested", then such a property may be specified in the fields parameter as child.items.nested.

Note
 Specifying nested properties in the fields query parameter may cause Link Expansion.
Note
 If a property with the specified name is not found in an object, the property name will be ignored.
Note
 Some object properties may be included in the representation even if not presented in the fields query parameter.
Example 2. Using the fields parameter
Request
GET /otdrs/R1_OPX-RTU_PRO16_556415?fields=mainframeId,opticalModuleSerialNumber
Response
200 OK
Content-Type: application/json
{
  "mainframeId": "OPX-RTU PRO16",
  "opticalModuleSerialNumber": "556415"
}

Some resources may reference another resources. Such referenced resources may be represented by a Link object. Such object has the only property:

"self"

URL to a referenced resource. It may be absolute or relative to the current request URL.

The client may want to make an additional request to the referenced resource URL, if it’s representation is needed.

Example 3. A Link object in representation
"tests" property contains a Link object
{
  "tests": {
    "self": "monitoring/tests"
  },
  "state": "disabled"
}

If the fields query parameter (see Requesting Arbitrary Fields) specifies a property in a referenced resource object, such an object will be expanded. It means that the Link object of the referenced resource will be replaced by the referenced resource representation object.

E.g., if a resource representation object has a property "referenced", which holds a Link object of a referenced resource, and if that referenced resource representation object in turn has a property "prop", and the client specifies ?fields=referenced.prop query, then the Link object will be replaced with a referenced resource representation object with the "prop" property.

Link expansion will be performed for all the referenced objects, which have fields specified in the fields query parameter.

Example 4. A request with no Link Expansion
Request
GET /monitoring/tests/3c8676c2-0486-4a7d-9c8d-a0862a45b1f5?fields=lastFailed
Response
200 OK
Content-Type: application/json
{
  "lastFailed": {
    "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/completed/last_failed"
  }
}
Example 5. A request with a Link Expansion
Request
GET /monitoring/tests/3c8676c2-0486-4a7d-9c8d-a0862a45b1f5?fields=lastFailed.traces
Response
200 OK
Content-Type: application/json
{
  "lastFailed": {
    "traces": {
      "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/completed/last_failed/traces"
    }
  }
}
Example 6. A request with a nested Link Expansion
Request
GET /monitoring/tests/3c8676c2-0486-4a7d-9c8d-a0862a45b1f5?fields=lastFailed.traces.items
Response
200 OK
Content-Type: application/json
{
  "lastFailed": {
    "traces": {
      "items": [
        {
          "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/completed/last_failed/traces/0"
        },
        {
          "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/completed/last_failed/traces/1"
        }
      ],
      "offset": 0,
      "total": 2
    }
  }
}

Resources

Monitoring

Monitoring is a process of periodically performing monitoring tests. The resource allows the client to get monitoring information and change monitoring settings.

URL

/monitoring
methods

GET, PATCH
representations

application/json, application/merge-patch+json

JSON representation contains the following properties:

"state"

a string, monitoring state. May be "disabled" or ‘"enabled"’;
"tests"

a Link object to the Tests resource.

JSON Merge Patch representation may contain exactly one of the following properties:

"state"

a string, target monitoring state. Can be "disabled" or "enabled".
Example 7. Get monitoring summary
Request
GET /monitoring
Response
200 OK
Content-Type: application/json
{
  "tests": {
    "self": "monitoring/tests"
  },
  "state": "disabled"
}
Example 8. Enable monitoring
Request
PATCH /monitoring
Content-Type: application/merge-patch+json
{
  "state":"enabled"
}
Response
200 OK

Tests

This is a collection of Test resources.

URL

/monitoring/tests
methods

GET, POST
representations

application/json

JSON representation contains the properties of the collection resource, with the "items" property holding Link objects to Test resources.

To create a new test the client must POST a JSON object with the following properties:

"id"

a string, a test identifier, which is used to distinguish this test from other tests. It may contain alphanumeric, hyphen and underscore characters.
"name"

an optional string, a name of the test. It may be used by the client for it’s own purposes.
"otdrId"

an optional string, an ID of an OTDR on which the monitoring test will be performed.
"otauPort"

an optional OTAU Port JSON-object, or explicit null if this test does not use OTAU.

The Otau Port JSON object holds properties which describe OTAU Port usage.

"otauId"

a string, an identifier of an OTAU, that will be used.
"portIndex"

an integer, a 0-based OTAU port index.

If the POST request succeeds, the server will respond with 201 Created code, Location header linking to a newly created Test resource.

Note
 If a test with the same "id" already exists, then the server will respond with the 409 Conflict.
Example 9. Get tests collection
Request
GET /monitoring/tests
Response
200 OK
Content-Type: application/json
{
  "items":[{
      "self":"tests/7db2faa6-333b-418c-99da-2b102ff2fa39"
    },{
      "self":"tests/53c24931-f98f-470a-a161-f69757218fad"
    },{
      "self":"tests/5f7e3d0b-4e7f-4c91-b048-b9cbeac7e200"
    }],
  "offset":0,
  "total":3
}
Example 10. Add a test
Request
POST /monitoring/tests
Content-Type: application/json
{
  "id":"7db2faa6-333b-418c-99da-2b102ff2fa39",
  "name":"some name",
  "otdrId":"R1_OPX-RTU_PRO16_556415"
}
Response
201 Created
Location: tests/7db2faa6-333b-418c-99da-2b102ff2fa39

Test

A monitoring can have multiple monitoring tests. A monitoring test is a part of monitoring process, which periodically makes OTDR measurements and compares the measured traces to reference traces.

Test resource contains information about a monitoring test and allows to change it’s settings.

URL

/monitoring/tests/<id> (<id> is a test id)
methods

GET, PATCH, DELETE
representations

application/json, application/merge-patch+json

JSON representation of the test resource contains the following properties:

"id"

a string, the test id.
"name"

a string, the test name.
"state"

a string, test state. May be "idle", "running" or "disabled".
"otdrId"

an string, an OTDR id.
"otauPort"

an optional object of OTAU Port id.
"period"

an integer, monitoring period in seconds.
"analysis_parameters"

a Link object to the current Analysis Parameters resource for this test.
"thresholds"

a Link object to the current Test Thresholds Set resource for this test.
"reference"

an optional Link object to the current Test Reference resource for this test.
"lastFailed"

an optional Link object to the last failed Completed Test.
"lastPassed"

an optional Link object to the last passed Completed Test.

JSON Merge Patch representation may contain one of the following properties:

"state"

a string, target test state. Can be "disabled" or "enabled".
"name"

a string, the test name.
"period"

an integer, the test monitoring period in seconds.
"otdrId"

an string, an OTDR id.
"otauPort"

an optional object of OTAU Port id.
Important
 Currently a test must have reference traces set so that the test may be enabled. Trying to PATCH with a "state" of "enabled" to a test not having reference traces set will result in a 409 Conflict server response. See Test References.

To remove a test the client must issue a DELETE request at the test URL.

Example 11. Get test information
Request
GET /monitoring/tests/3c8676c2-0486-4a7d-9c8d-a0862a45b1f5
Response
200 OK
Content-Type: application/json
{
  "id": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5",
  "lastFailed": {
    "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/completed/last_failed"
  },
  "lastPassed": {
    "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/completed/last_passed"
  },
  "name": "New name",
  "otauPort": {
    "otauId": "S1___8",
    "portIndex": 2
  },
  "otdrId": "R1_OPX-RTU_PRO16_556415",
  "period": 3660,
  "reference": {
    "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/references/current"
  },
  "state": "idle",
  "thresholds": {
    "self": "3c8676c2-0486-4a7d-9c8d-a0862a45b1f5/thresholds/current"
  }
}
Example 12. Enable test
Request
PATCH /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369
Content-Type: application/merge-patch+json
{
  "state":"enabled"
}
Response
200 OK
Example 13. Change test name
Request
PATCH /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369
Content-Type: application/merge-patch+json
{
  "name":"New name"
}
Response
200 OK
Example 14. Set test monitoring period
Request
PATCH /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369
Content-Type: application/merge-patch+json
{
  "period":32
}
Response
200 OK
Example 15. Set test OTDR ID
Request
PATCH /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369
Content-Type: application/merge-patch+json
{
  "otdrId": "R1_OPX-RTU_PRO16_556415"
}
Response
200 OK
Example 16. Set test OTAU port
Request
PATCH /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369
Content-Type: application/merge-patch+json
{
  "otauPort": {
    "otauId": "S1___8",
    "portIndex": 3
  }
}
Response
200 OK
Example 17. Set test to not use OTAU
Request
PATCH /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369
Content-Type: application/merge-patch+json
{
  "otauPort": null
}
Response
200 OK
Example 18. Remove a test
Request
DELETE /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369
Response
200 OK

Completed Test

Completed test object contains results of a single run of a monitoring test.

URL

/monitoring/test/<id>/completed/<kind> (<id> is a test id, <kind> is either last_passed or last_failed)
methods

GET
representations

application/json

The JSON representation of the completed test resource contains the following properties:

"started"

a string, the test run start time in the ISO 8601 format,
"result"

a string, one of "ok" or "failed",
"extendedResult"

an optional string, one of "no_fiber", "fiber_damage", "otau_failed" or "otdr_failed",
"traces"

an optional Link object of a Traces resource,
"type"

a string, either "regular_check" or "auto_reference_detection",
"eventLocation"

an optional number, event location in meters,
"report"

an optional Link object of a Report resource.

Currently, only if the "extendedResult" property equals to "fiber_damage", the "eventLocation" property is set and holds the fiber damage location.

Example 19. Get last passed run test information
Request
GET /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/completed/last_passed
Response
200 OK
Content-Type: application/json
{
  "report":{
    "self":"last_passed/report"
  },
  "result":"ok",
  "started":"2015-03-16T23:18:01Z",
  "traces":{
    "self":"last_passed/traces"
  },
  "type": "regular_check"
}

Test References

The resource allows the client to set reference traces or schedule an automatic reference detection for a monitoring test.

URL

/monitoring/test/<id>/references (<id> is a test id)
methods

POST
representations

multipart/form-data, application/json

To set new reference SOR-traces for a monitoring test the client must POST them in multipart/form-data content, either as separate files or in a single ZIP file, as described in Resource Representation Format.

To schedule an automatic reference detection the client must POST an application/json object with the following properties:

"type"

a string, type of reference, must be "software_pending" for automatic reference detection;
"opticalLineProperties"

an object, containing optical line properties (see, below).

The optical line properties are the following:

"refractiveIndex"

a floating point value, refractive index of an optical line;
"backscatterCoefficient"

a floating point value, backscatter coefficient of an optical line.

If the POST request succeeds, the server will respond with 201 Created code and Location header linking to a newly created Test Reference resource.

Example 20. Set reference traces for a monitoring test
Request
POST /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/references
Content-Type: multipart/form-data; boundary=00000FormBoundary14d4796a757
Content-Length: 33287
00000FormBoundary14d4796a757
Content-Disposition: form-data; name="files"; filename="file1.sor"
Content-Type: application/octet-stream

<message part body>
00000FormBoundary14d4796a757
Content-Disposition: form-data; name="files"; filename="file2.sor"
Content-Type: application/octet-stream

<message part body>
00000FormBoundary14d4796a757--
Response
201 Created
Location: ed838f74-5fa2-490f-abbb-38d995a1b369/references/current
Example 21. Schedule an automatic reference detection for a monitoring test
Request
POST /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/references
Content-Type: application/json
{
  "type" : "software_pending",
  "opticalLineProperties" : {
    "refractiveIndex" : 1.4686,
    "backscatterCoefficient" : -80
  }
}
Response
201 Created
Location: ed838f74-5fa2-490f-abbb-38d995a1b369/references/current

Test Reference

The resource contains information about test reference traces.

URL

/monitoring/test/<id>/references/current (<id> is a test id)
methods

GET
representations

application/json

JSON representation of a test reference resource contains the following properties:

"traces"

an optional Link object to a Traces resource.
"type"

a string, containing the test reference type, either "user", "software" or "software_pending",
"report"

an optional Link object of a Report resource.
Example 22. Get current test reference information
Request
GET /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/references/current
Response
200 OK
Content-Type: application/json
{
  "report":{
    "self":"current/report"
  },
  "traces":{
    "self":"current/traces"
  },
  "type":"user"
}

Test Thresholds Sets

The resource allows the client to set thresholds for a monitoring test.

URL

/monitoring/test/<id>/thresholds (<id> is a test id)
methods

POST
representations

application/json

To set new thresholds for a test monitoring the client must POST an application/json representation of the Test Thresholds Set resource.

If the POST request succeeds, the server will respond with 201 Created code and Location header linking to a newly created Test Thresholds Set resource.

Example 23. Set thresholds for a monitoring test
Request
POST /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/thresholds
Content-Type: application/json
{
  "levels":[{
      "groups":[{
          "scope":{
            "event_indices":[-1]
          },
          "thresholds":{
          }
        }]
    }]
}
Response
201 Created
Location: ed838f74-5fa2-490f-abbb-38d995a1b369/thresholds/current

Test Thresholds Set

The resource contains information about current monitoring test thresholds.

URL

/monitoring/test/<id>/thresholds/current (<id> is a test id)
methods

GET
representations

application/json

JSON representation of a monitoring test thresholds resource contains the following properties:

"levels"

an array of the thresholds levels.

Each thresholds level contains the following properties:

"name"

an optional string, which holds the name of the level,
"groups"

an array of the thresholds scoped groups of the level.

Each thresholds scoped group contains the following properties:

"scope"

an optional thresholds group scope,
"thresholds"

(non-scoped) thresholds group.

A (non-scoped) thresholds group contains the following properties:

"event_loss"

an optional combined threshold for event loss,
"event_reflectance"

an optional combined threshold for event reflectance,
"event_leading_loss_coefficient"

an optional combined threshold for event leading loss coefficient.

Each combined threshold contains the following properties:

"min"

an optional floating point value, which holds a absolute minimum threshold,
"max"

an optional floating point value, which holds a absolute maximum threshold,
"decrease"

an optional (negative) floating point value, which holds a relative minimum threshold,
"increase"

an optional floating point value, which holds a relative maximum threshold.
Example 24. Get current test thresholds
Request
GET /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/thresholds/current
Response
200 OK
Content-Type: application/json
{
  "levels":[{
      "groups":[{
          "scope":{
            "event_indices":[-1]
          },
          "thresholds":{
          }
        }]
    }]
}

Traces

Traces resource is a Binary Collection Resource which holds Trace resources.

URL

may be different
methods

GET
representations

application/json, application/octet-stream

Depending on a value of the Accept HTTP request header (see, HTTP Headers), the server provides either application/octet-stream or application/json representation (see, Resource Representation Format) of the measurement trace.

For ZIP representation format of the collection, client can also choose a representation format of trace items in the collection, by using trace_format query variable. Possible values of the trace_format variable are the following:

sor

Each trace will be represented in SOR format.
csv

Each trace will be represented in CSV format.
csv_and_sor

Each trace will be represented in both SOR and CSV formats. If the trace_format variable is missing, then each trace will be represented in SOR format.
Example 25. Get test current reference traces as a JSON
Request
GET /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/references/current/traces
Accept: application/json
Response
200 OK
Content-Type: application/json
{
  "items":[{
      "self":"traces/0"
    },{
      "self":"traces/1"
    }],
  "offset":0,
  "total":2
}
Example 26. Get test current reference traces as a ZIP-file
Request
GET /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/references/current/traces
Accept: application/octet-stream
Response
200 OK
Content-Type: application/octet-stream
Content-Length: 66245
Content-Disposition: attachment; filename="reference-traces.zip"
<binary data>
Example 27. Get test current reference traces as a ZIP-file of CSV files
Request
GET /monitoring/tests/ed838f74-5fa2-490f-abbb-38d995a1b369/references/current/traces?trace_format=csv
Accept: application/octet-stream
Response
200 OK
Content-Type: application/octet-stream
Content-Length: 123434
Content-Disposition: attachment; filename="reference-traces.zip"
<binary data>

Trace

Trace resource represents measurement data, obtained during an OTDR measurement, during a monitoring, or uploaded by the client. The default trace representation format is SOR. The server can also alternatively represent a trace in CSV format.

URL

may be different
methods

GET
representations

application/octet-stream, text/csv

In addition to the common way of selecting a resource representation with the Accept request header, a trace resource representation may also be chosen with the extension in the filename part of URL. I.e., traces/0.sor will select the application/octet-stream (SOR) representation, while traces/0.csv will select the text/csv (CSV) representation. If neither Accept header nor extension is specified, then the server chooses the default resource representation format, which is application/octet-stream (SOR) for the trace resource. If both Accept header and extension are specified, then extension takes precedence.

Example 28. Get OTDR measurement trace as binary data
Request
GET /measurements/964c98cd-6fbb-4313-932d-275111538937/traces/0
Accept: application/octet-stream
Response
200 OK
Content-Type: application/octet-stream
Content-Length: 32079
Content-Disposition: attachment; filename="measurement.sor"
<Binary content>
Example 29. Get OTDR measurement trace as CSV data
Request
GET /measurements/964c98cd-6fbb-4313-932d-275111538937/traces/0.csv
Response
200 OK
Content-Type: text/csv
Content-Length: 64346
Content-Disposition: attachment; filename="measurement.csv"
<CSV content>

Report

Report resource contains a report information for an OTDR measurement trace or several traces, measured manually or during monitoring.

URL

may be different
methods

GET
representations

text/html or application/pdf

In addition to the common way of selecting a resource representation with the Accept request header, a report resource representation may also be chosen with the extension in the filename part of URL. I.e., report.html will select the text/html representation, while report.pdf will select the application/pdf representation. If neither Accept header nor extension is specified, then the server chooses the default resource representation format, which is text/html for the report resource. If both Accept header and extension are specified, then extension takes precedence.

Example 30. Get OTDR measurement report
Request
GET /measurements/964c98cd-6fbb-4313-932d-275111538937/report
Response
200 OK
Content-Type: text/html
Content-Length: 14340
<HTML content>
Example 31. Get OTDR measurement report in PDF format
Request
GET /measurements/964c98cd-6fbb-4313-932d-275111538937/report.pdf
Response
200 OK
Content-Type: application/pdf
Content-Length: 34456
Content-Disposition: attachment; filename="report.pdf"
<PDF content>

OTAUs

This is a collection of OTAU resources.

URL

/otaus
methods

GET
representations

application/json

JSON representation contains the properties of the collection resource, with the "items" property holding Link objects to OTAU resources.

Example 32. Get OTAUs collection
Request
GET /otaus
Response
200 OK
Content-Type: application/json
{
  "items": [
    {
      "self": "otaus/S1___8"
    }
  ],
  "offset": 0,
  "total": 1
}

OTAU

The OTAU resource contains information about an OTAU device connected to the RTU.

URL

/otaus/<id> (<id> is an OTAU id)
methods

GET
representations

application/json

The OTAU JSON representation object contains the following properties:

"id"

a string, the OTAU id,
"model"

an optional string, the OTAU model,
"serialNumber"

an optional string, the OTAU serial number,
"portCount"

an optional integer, number of optical ports in the OTAU.
Example 33. Get OTAU information
Request
GET /otaus/S1-8
Response
200 OK
Content-Type: application/json
{
  "id":"S1-8",
  "model":"FOSB",
  "portCount":8,
  "serialNumber":"12345678"
}

OTDRs

This is a collection of OTDR resources.

URL

/otdrs
methods

GET
representations

application/json

JSON representation contains the properties of the collection resource, with the "items" property holding Link objects to OTDR resources.

Example 34. Get OTDRs collection
Request
GET /otdrs
Response
200 OK
Content-Type: application/json
{
  "items": [
    {
      "self": "otdrs/R1_OPX-RTU_PRO16_556415"
    }
  ],
  "offset": 0,
  "total": 1
}

OTDR

The OTDR resource contains information about an OTDR embedded in the RTU.

URL

/otdrs/<id> (<id> is an OTDR id)
methods

GET
representations

application/json

The OTDR JSON representation object contains the following properties:

"id"

a string, the OTDR id,
"mainframeId"

an optional string, the OTDR mainframe identifier,
"opticalModuleSerialNumber"

an optional string, the OTDR optical module serial number,
"supportedMeasurementParameters"

an object, measurement parameters supported by the OTDR.

OTDR supports setting some measurement parameters only from a limited list of supported values. Moreover, the supported lists of several measurement parameters depend on selected values of other measurement parameters. The measurement parameters, supported by OTDR are listed and described below.

Laser unit - a unit, which emits laser pulses to perform an OTDR measurement. In the API a unit is identified by a string, which contains a laser nominal wavelength in nanometers, and a prefix, describing whether the the laser is multi-mode or single-mode. E.g., "SM1310". Each laser unit may support different distance ranges.

Distance range - maximum value of measured distances. This parameter determines the optical pulse repetition period which should be longer than double time of the optical pulse passing in the optical fiber. The value of distance range should exceed the probable length of the line under measurement. In the API a distance range is represented as a string value, which is a distance in kilometers. E.g., "160", "10", "2.0", "0.50". Each distance range, supported by a laser unit, may support different resolutions, averaging times, fast averaging times and pulse durations.

Resolution - distance between two samples (sampling interval) of the trace. In the API a resolution is represented as a string value, which is distance in meters. E.g., "0.16". There is a special resolution value, "AUTO", which means that best actual resolution will be determined automatically, depending on other measurement parameters.

Averaging time - the time, which is spent during a measurement to perform averaging of collected measurement data. This is the major measurement time summand, which mostly determines the whole duration of the measurement process. This is an approximate value. In the API an averaging time is represented as a string in form "MM:SS", where MM represents minutes, and SS represents seconds. E.g., "00:05", "01:00".

Fast averaging time - the time, which is spent during a fast measurement to perform averaging of collected measurement data. It has the same meaning as the averaging time, but is appliable for fast measurements, i.e. measurements optimized for short duration time. In the API a fast averaging time is represented as a string, which holds time in seconds. E.g., "0.5", "2.0".

Pulse duration - the value of the probe optical pulse duration. In the API a pulse duration is represented as a string, which holds pulse duration in nanoseconds. E.g., "6", "100".

Thus, the "supportedMeasurementParameters" property of the JSON representation above holds a nested object which represents a tree-like relationships between measurement parameters supported by the OTDR. The nested objects contain the following names: "laserUnits", "distanceRanges", "resolutions", "averagingTimes", "fastAveragingTimes", "pulseDurations". An example of such an object is listed below.

Example 35. Get OTDR information
Request
GET /otdrs/R1-OPX-RTU-PRO16-556415
Response
200 OK
Content-Type: application/json
{
    "id":"R1-OPX-RTU-PRO16-556415",
    "mainframeId": "PRO5",
    "opticalModuleSerialNumber": "95214",
    "supportedMeasurementParameters": {
        "laserUnits": {
            "SM1550": {
                "distanceRanges": {
                    "0.50": {
                        "averagingTimes": [
                            "00:05",
                            "00:15",
                            "00:30",
                            "01:00"
                        ],
                        "fastAveragingTimes": [
                            "0.2",
                            "0.5",
                            "1.0",
                            "2.0"
                        ],
                        "pulseDurations": [
                            "6",
                            "12",
                            "25",
                            "100"
                        ],
                        "resolutions": [
                            "AUTO",
                            "0.16",
                            "0.32",
                            "0.64"
                        ]
                    },
                    "10": {
                        "averagingTimes": [
                            "00:05",
                            "00:15",
                            "00:30",
                            "01:00",
                            "03:00"
                        ],
                        "fastAveragingTimes": [
                            "0.2",
                            "0.5",
                            "1.0",
                            "2.0"
                        ],
                        "pulseDurations": [
                            "6",
                            "12",
                            "25",
                            "100",
                            "300",
                            "1000"
                        ],
                        "resolutions": [
                            "AUTO",
                            "0.32",
                            "1.3",
                            "2.6"
                        ]
                    },
                    "2.0": {
                        "averagingTimes": [
                            "00:05",
                            "00:15",
                            "00:30",
                            "01:00",
                            "03:00"
                        ],
                        "fastAveragingTimes": [
                            "0.2",
                            "0.5",
                            "1.0",
                            "2.0"
                        ],
                        "pulseDurations": [
                            "6",
                            "12",
                            "25",
                            "100"
                        ],
                        "resolutions": [
                            "AUTO",
                            "0.16",
                            "0.32",
                            "0.64"
                        ]
                    },
                    "5.0": {
                        "averagingTimes": [
                            "00:05",
                            "00:15",
                            "00:30",
                            "01:00",
                            "03:00"
                        ],
                        "fastAveragingTimes": [
                            "0.2",
                            "0.5",
                            "1.0",
                            "2.0"
                        ],
                        "pulseDurations": [
                            "6",
                            "12",
                            "25",
                            "100",
                            "300"
                        ],
                        "resolutions": [
                            "AUTO",
                            "0.16",
                            "0.64",
                            "1.3"
                        ]
                    }
                }
            }
        }
    }
}

OTDR Measurements

OTDR measurements resource allow starting an OTDR measurement with specified measurement parameters.

URL

/measurements
methods

POST
representations

application/json

To start a measurement the client must provide a JSON object with the following properties:

"id"

a string, OTDR measurement identifier, which is used to distinguish this measurement from others. It may contain alphanumeric, hyphen and underscore characters.
"otdrId"

a string, an ID of an OTDR used for measurement.
"otauPort"

an optional OTAU Port object.
"otdrParameters"

an object, OTDR measurement parameters.
"analysisParameters"

an object, optical analysis parameters.

The JSON OTDR measurement parameters object contains the following properties:

"measurementType"

a string, measurement type, see below,
"laserUnit"

an optional string, laser unit, one of supported laser units,
"distanceRange"

an optional string, distance range, one of supported distance ranges,
"pulseDuration"

an optional string, pulse duration, one of supported pulse durations,
"averagingTime"

an optional string, averaging time, one of supported averaging times (or fast averaging times, if "fastMeasurement" is true),
"resolution"

an optional string, time resolution, one of supported time resolutions,
"highFrequencyResolution"

an optional boolean (false by default), when true, then high frequency trace signal won’t be filtered out, which may improve dead zone measurement with the price of worse dynamic range,
"fastMeasurement"

an optional boolean (false by default), when true, fast measurement (i.e., measurement optimized for shortest duration) will be performed,
"maxPointCount"

an optional integer, which limits max number of data points in the resulting trace (may be set only if "fastMeasurement" is true),
"opticalLineProperties"

an object, containing properties of an optical line (see, above),
"requiredConnectionQualities"

an array of Connection Quality objects (see below).

The "measurementType" property may be one of the following values:

"manual"

a measurement with all the measurement parameters set manually; with this measurement type all the measurement parameters from the list above are required to be provided; this type of measurement generates a single SOR-trace;
"auto"

a measurement on a single laser unit with all the other optional measurement parameters detected automatically; with this measurement type only the "laserUnit" optional measurement parameter is required to be provided; this type of measurement generates a single SOR trace;
"vscout_single_laser"

a measurement on a single laser unit with all the other optional measurement parameters detected automatically; with this measurement type only the "laserUnit" optional measurement parameter is required to be provided; this type of measurement may generate multiple SOR traces;
"vscout_all_lasers"

a measurement on all the OTDR’s laser units with the optional measurement parameters detected automatically; with this measurement type no optional measurement parameters are required to be provided; this type of measurement may generate multiple SOR traces.

For OTDR supported measurement parameters see the "supportedMeasurementParameters" propterty of the OTDR resource JSON representation object.

The Connection Quality object holds required (when sent by a client within a request body) or actual (when sent by a device within a response body) quality of an optical connection. It contains the following properties:

"laserUnit"

an optional string, laser unit, one of supported laser units,
"loss"

an optional number, optical loss in dB,
"reflectance"

an optional number, optical reflectance in dB.

The JSON optical analysis parameters object contains the following properties:

"macrobendThreshold"

an optional number, macrobend threshold in dB. This threshold determines, when the same event on two different traces, measured on different wavelengths, will be considered as a macrobend event.

If the POST request succeeds, the server will respond with 201 Created code, Location header linking to a newly created OTDR Measurement resource, and response body containing the current OTDR Measurement resource representation.

Important
 Currently RTU monitoring must be disabled to allow manual OTDR measurements through the API. Otherwise, starting a manual OTDR measurement will result in a 409 Conflict server response.
Note
 If a measurement with the same "id" already exists on the server, then the server will respond with the 409 Conflict.
Important
 For storage reasons the number of measurements, simultaneously stored on the server, may be limited. Thus, starting a new measurement may result in the oldest stored measurement being removed from the server.
Example 36. Start an OTDR measurement
Request
POST /measurements
{
 "id" : "964c98cd-6fbb-4313-932d-275111538937",
 "otdrId" : "R1_OPX-RTU_PRO16_556415",
 "otauPort": {
   "otauId": "S1___8",
   "portIndex": 2
 },
 "otdrParameters" : {
   "measurementType" : "manual",
   "laserUnit" : "SM1310",
   "distanceRange" : "0.50",
   "pulseDuration" : "25",
   "averagingTime" : "00:05",
   "resolution" : "0.16",
   "opticalLineProperties" : {
     "backscatterCoefficient" : -81,
     "refractiveIndex" : 1.4682,
   },
   "analysisParameters" : {
     "eventLossThreshold" : 0.02,
     "eventReflectanceThreshold" : -65,
     "endOfFiberThreshold" : 25
   },
   "requiredConnectionQualities" : [
      {
        "loss" : 1.5,
        "reflectance" : -35
      }
    ]
  }
}
Response
201 Created
Content-Type: application/json
Location: measurements/964c98cd-6fbb-4313-932d-275111538937
{
  "status":"started",
  "id":"964c98cd-6fbb-4313-932d-275111538937"
}

OTDR Measurement

After starting an OTDR measurement the client can check it’s status or delete it through an OTDR measurement resource.

URL

/measurements/<id> (<id> is a measurement identifier, assigned by the client when starting measurement)
methods

GET, DELETE
representations

application/json

JSON representation of an OTDR measurement resource contains the following properties:

"id"

a string, measurement identifier, assigned by the client when starting measurement.
"status"

a string, containing the measurement status, may have one of the following values: "started", "failed" or "finished".
"extendedStatus"

an optional string, containing the extended measurement status, may be either "otau_failed", "otdr_failed" or "bad_connection_quality".
"traces"

an optional Link object, to a Traces resource, if the measurement succeeded,
"report"

an optional Link object of a Report resource.
"connectionQualities"

an array of Connection Quality objects (see above).

To remove a measurement the client must issue a DELETE request at the measurement URL.

Example 37. Get OTDR measurement
Request
GET /measurements/964c98cd-6fbb-4313-932d-275111538937
Response
200 OK
Content-Type: application/json
Location: 964c98cd-6fbb-4313-932d-275111538937
{
  "connectionQualities": [
    {
      "laser_unit": "SM1550",
      "loss": 0.5886816978455,
      "reflectance": -41.806226730347
    }
  ],
  "id":"964c98cd-6fbb-4313-932d-275111538937",
  "report":{
    "self":"964c98cd-6fbb-4313-932d-275111538937/report"
  },
  "status":"finished",
  "traces":{
    "self":"964c98cd-6fbb-4313-932d-275111538937/traces"
  }
}
Example 38. Remove a measurement
Request
DELETE /measurements/964c98cd-6fbb-4313-932d-275111538937
Response
200 OK

Notification Settings

The Notification Settings resource allows to set and get parameters for Notifications.

URL

/notification/settings
methods

GET, PATCH
representations

application/json, application/merge-patch+json

JSON representation contains the following properties:

"state"

an string, notifier state. May be "disabled" or "enabled";
"url"

an optional string, URL notifications are posted to.
"eventTypes"

an optional array, containing types of events, which are posted to the URL.

JSON Merge Patch representation contains the following properties:

"state"`

an optional string, notifier state. May be "disabled" or "enabled";
"url"

an optional string, URL notifications are posted to.
"eventTypes"

an optional array, containing types of event, which are posted to the URL.
Example 39. Get notification settings
Request
GET /notification/settings
Response
200 OK
Content-Type: application/json
{
  "state": "enabled",
  "eventTypes": [
    "monitoring_test_failed",
    "monitoring_test_passed"
  ],
  "url": "http://192.168.96.163:12345/"
}
Example 40. Change notification settings
Request
PATCH /notification/settings
Content-Type: application/merge-patch+json
{
  "state" : "enabled",
  "eventTypes": [
    "monitoring_test_failed",
    "monitoring_test_passed"
  ],
  "url" : "http://192.168.96.163:12345/"
}
Response
200 OK

Notifications (Callbacks)

The RTU can be set up so that it will notify a server via configurable URL, when events of selected types occurs. The notification settings can be queries and changed via the Notification Settings Resource. When notifications are enabled, RTU sends a special JSON object to the configurable URL with the POST HTTP request. If there is a communication failure, or the server responds with an HTTP status code other than 200, then the RTU will try to resend the events periodically.

URL

configurable
methods

POST
representations

application/json

The JSON object contains the following fields:

"rtuId"

a string, RTU identifier;
"type"

a string, "event_callback";
"events"

an array, which contains event objects.

Each event object contains the following fields:

"type"

a string, type of event;
"time"

a string, event occurance time in ISO 8601 format;
"data"

an optional object, containing event payload, which depends on event type.

The following event types are currently supported:

"monitoring_test_failed"

occurs when a monitoring test fails;
"monitoring_test_passed"

occurs when a monitoring test passes;
Example 41. Notification when a monitoring test passes
Request
POST /some/url
Content-Type: application/json
{
  "events": [{
      "data": {
        "result": "ok",
        "started": "2016-12-19T19:37:00Z",
        "testId": "af72f984-2f7c-4a44-9df9-9d3d6f3b41c2",
        "type": "regular_check"
      },
      "time": "2016-12-19T19:37:09Z",
      "type": "monitoring_test_passed"
    }
  ],
  "rtuId": "2",
  "type": "event_callback"
}
Response
200 OK
Example 42. Notification when a monitoring test fails
Request
POST /some/url
Content-Type: application/json
{
  "events": [{
      "data": {
        "extendedResult": "trace_change",
        "result": "failed",
        "started": "2016-12-19T19:36:51Z",
        "testId": "161f7a8f-9ac9-4b53-bcea-528e55dca547",
        "traceChange": {
          "changeLocation": 0.0024911238166462333,
          "changeType": "fiber_break",
          "currentEventIndex": 1,
          "currentEventType": "other",
          "referenceEventIndex": 0,
          "referenceEventMapsToCurrentEvent": false,
          "referenceEventType": "other"
        },
        "type": "regular_check"
      },
      "time": "2016-12-19T19:37:00Z",
      "type": "monitoring_test_failed"
    }
  ],
  "rtuId": "2",
  "type": "event_callback"
}
Response
200 OK