Service Diagnostics
Enables the use of Lumen internal triage logic to assist in isolating trouble points or identifying possible performance issues with Lumen services.
Functional Overview
Lumen Service Diagnostics APIs enable the use of Lumen’s internal triage logic to assist in isolating trouble points or identifying possible performance issues with Lumen services. API access allows use of this logic for customers to create their own UI or process flows that will use the Lumen next suggested actions to better understand the current state of a customer service. This document provides technical information that Lumen customers may use to access the Service Diagnostics APIs and interpret the responses or error messages when interfacing with the APIs. It does not intend to provide technical training on the individual dispositions and how they are interpreted on networks or within systems.
Intended User (Target Audience)
The Service Diagnostics APIs are only for use by approved Lumen Customers. All of the Lumen customers who intend to use Service Diagnostics APIs should request access for API Marketplace and complete the required authentication and authorization prerequisites before accessing the APIs. The Service Diagnostics APIs and associated technology should be used by someone who is familiar with API interfaces, REST, and JSON.
Service Diagnostics APIs are designed to most effectively support Lumen Layer 3 (IP associated) services at this time and will be expanding into other product delivery types in future releases.
Business Benefits
Lumen Service Diagnostics APIs allow a Customer to directly call APIs from their own application instead of having to login to a Lumen system or front end application to get this information. This should enable a more efficient process for self-diagnosing services, viewing connection statuses, and creating tickets from their own applications. The Service Diagnostics APIs are not intended to be used as a persistent state check on any or all services on a repetitive basis and are intended to be used in a flow process when a services issue is detected, expected, or has been previously reported and additional information is needed.
Quick Start Guide
- Enroll in Service Diagnostics APIs. Contact your account representative to assist with enrolling.
- Register user and API Apps
- Obtain API keys. Upon enrollment you will receive test credentials to access any available test environments, and production credentials will move to approved status.
- Setup authorization. Using the Navigation bar go to Code Samples for sample code for setting up authorization.
- Make your first call. Using the Navigation bar go to the Documentation/Specification section:
- Click on the Authorize button and add your Test credentials.
- Select the Service Diagnostics GET/service/detail API.
- Click on the “Try it out” button.
- Fill in the Parameters.
- Click the Execute button to see the response.
Lumen supports the OAuth 2.0 client credentials authorization grant flow for external access by client-side applications.
Only existing Lumen customers can access the Service Diagnostics APIs. Please contact your account manager to begin the enrollment process, or see the Support section for more information. Upon enrollment you will receive instructions on how to get started. Once your application is approved you can go to Using OAuth 2.0 for detailed steps on getting a Bearer token using basic authorization base64 encoding.
Credential |
Description |
Example |
---|---|---|
user_name |
Email address that grants you access to the developer portal and application registration |
|
password |
Password for accessing developer portal |
password123! |
client_id |
Application specific credential used to obtain bearer token |
KylFl1J5hGdEAYvxvmXf7ekeO0La3cLo |
client_secret |
Application password used to obtain bearer token |
wH1GnMPZEMlMTlHQ |
access_token |
A current unique OAuth2 bearer token for your application |
PPhwBYy6HYm2FqMNCqVUwnaxi4d6 |
Credential |
Description |
Example |
---|---|---|
authorization |
Your application's unique API token. Always required. |
Bearer PPhwBYy6HYm2FqMNCqVUwnaxi4d6 |
Examples using curl
Retrieve a current OAuth2 token
curl --request POST -d grant_type=client_credentials -u ${Consumer_Key}:${Consumer_Secret} https://api.lumen.com/oauth/token
Retrieve diagnostics detail report for a service (v2)
curl --request GET -H 'accept: application/json' -H "Authorization: Bearer ${OAuth2_Token}" 'https://api.lumen.com/ServiceAssurance/v2/Diagnostics/service/detail?serviceId=${Service_Id}'
Extract PDF Summary from JSON response of detail report (v2)
A PDF summary file is contained in the Detail API JSON response.
To view the PDF file follow these steps
- extract the “pdf” JSON element
- strip off the leading text descriptor: data:application/pdf;base64
- decode the remainder as base64
- save to a file with .pdf extension
Here is an example:
curl --request GET -H 'accept: application/json' -H "Authorization: Bearer ${OAuth2_Token}" \ 'https://api.lumen.com/ServiceAssurance/v2/Diagnostics/service/detail?serviceId=${Service_Id}' \
| jq -r .data[0].pdf | sed 's/data:application\/pdf;base64,//' | base64 --decode > summary.pdf
200 - OK
400 - Bad Request
403 - Forbidden
404 - Not Found
500 - Internal Server Error
503 - Service Unavailable
Should you have any questions or issues with this API please click here to contact us.