How to use the API – API Developer

The below information contains use cases on how to use Enables Line Test API.

Prerequisites:

You must have access to a valid client ID and secret of an active application that has been granted the required Line Test API scopes in Enables Identity and Access Management platform, Okta.
- If you are not sure how to generate an access token, start here.
A service must exist that the user has permission to perform a Line Test on.

Creating a Line Test and retrieving a result

This example explains how to perform a Line Test for a service and retrieve the results.

Steps:

Generate an access token via the Auth v2 API that contains the following scopes
- 'linetestAPI.read' - This allows the client to retrieve the Line Test result.
- 'linetestAPI.write' - This allows the client to submit a Line Test for processing.
- 'RSPCode.{insert rsp code}' - This allows the client to access services owned by this RSP. An example would be 'RSPCode.ENA' which would allow access to services like 'ENENAB02123456'. Multiple RSPCode scopes can be applied to allow the access token to access more services.
Submit a Line Test to the Line Test API 'POST /tests' endpoint with the serviceId and test type (ontStatus).
- Note, to reduce complexity in integrating with multiple LFCs, Enable has followed Chorus's API structure, which is why there is reference to 'productId' in the Line Test API spec. The value of a 'productId' in Enables Line Test API is a 'serviceId'.
Wait some time before beginning to poll for a result.
- It is suggested to wait 10 seconds before beginning to poll, however response times will vary and it is upto the client to decide when to begin polling.
Poll the Line Test API 'GET /test/{testId}' endpoint to see the result of the Line Test.
- If the result is a 202 response, the Line Test has not been processed yet. Wait some time and poll the Line Test API 'GET /test/{testId}' endpoint again.
  - It is suggested to wait at least 5 seconds between each poll, however the polling frequency is upto the client.
- If the result is a 200 response, the details of the Line Test result will be included in the response body.
  - Please Note, the Line Test API is designed to return as much information as possible about the service, however if the service is misconfigured or downstream applications return errors, the Line Test API will not be able to display the results and will return null values.

Below is a Python3 example of performing a Line Test.

import time
import requests
import json
import uuid

'''
Step 1: Generate an access token via the Auth v2 API and ensure it has the following scopes.
- linetestAPI.read
- linetestAPI.write
- RSPCode.{insert the owning RSP code here. Example: RSPCode.ENA} # Note, multiple RSP codes 
can be used in the same access token.

For details on how to generate an access token, please refer to the API documentation 
here: https://api-developer.enable.net.nz/hc/en-nz/articles/32166117952409-How-to-use-the-API
'''

token = 'your-access-token-here' # Replace with your actual access token

'''
Step 2: Submit a request for a Line Test for a service that the access token has been 
granted access to. (I.e in this example the scope used is RSPCode.ENA which allows 
access to ENA services, so the serviceId used will be ENENAB02123456)
'''

service_id = 'ENENAB02123456' # Replace with the actual service ID you want to test

url = "https://apis.enable.net.nz/linetest/v1/tests"
payload = json.dumps({
    "productId": f"{service_id}",
    "test": {
        "testType": "ontStatus"
    }
})

headers = {
    'x-transaction-id': str(uuid.uuid4()),
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {token}'
}

response = requests.request("POST", url, headers=headers, data=payload)
test_id = response.json().get('testId')

'''
Step 3: Wait some time for the test to be processed and then poll the API for the test result.
'''

time.sleep(10)

'''
Step 4: Poll the Line Test API for the test result.
'''

attempts = 0
while attempts < 10:
    url = f"https://apis.enable.net.nz/linetest/v1/tests/{test_id}"
    payload = {}
    headers = {
        'x-transaction-id': str(uuid.uuid4()),
        'Authorization': f'Bearer {token}'
    }

    response = requests.request("GET", url, headers=headers, data=payload)
    if response.status_code == 202:
        print("Line Test is still processing...")
        time.sleep(5) # Wait for sometime before polling again. It is suggested to implement 
                      # an exponential backoff strategy here.
        attempts += 1
    elif response.status_code == 200:
        print("Line Test completed successfully.")
        print(response.text)
        break
    else:
        response.raise_for_status()

Searching historical Line Tests

This example explains how to view historical Line Tests by searching with the Line Test API.

Steps:

Perform a Line Test on a service (See above example)
- Before you can search for all Line Tests for a service, a minimum of 1 Line Test must have been created. Follow the example above 'Creating a Line Test and retrieving a result' to create a Line Test for a service.
Perform a search using the Line Test API 'GET /tests' endpoint.
- This will return all Line Tests for this service.
- This API endpoint supports pagination and has various pagination controls as part of the request parameters.

Below is a Python3 example of searching historical Line Tests

import requests
import uuid

'''
Step 1: Generate an access token via the Auth v2 API and ensure it has the following scopes.
- linetestAPI.read
- RSPCode.{insert the owning RSP code here. Example: RSPCode.ENA} # Note, multiple RSP codes
 can be used in the same access token.

For details on how to generate an access token, please refer to the API documentation 
here: https://api-developer.enable.net.nz/hc/en-nz/articles/32166117952409-How-to-use-the-API
'''

token = 'your-access-token-here' # Replace with your actual access token

'''
Step 2: Submit a request to return historical Line Tests for a service that the access 
token has been granted access to. (I.e in this example the scope used is RSPCode.ENA which 
allows accss to ENA services, so the serviceId used will be ENENAB02123456)
'''

service_id = 'ENENAB02123456' # Replace with your actual service ID
count = 20
offset = 0

url = f"https://apis.enable.net.nz/linetest/v1/tests?productId={service_id}&count={count}&offset={offset}"

payload = {}
headers = {
    'x-transaction-id': str(uuid.uuid4()),
    'Authorization': f'Bearer {token}'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)