# CityFibre - Service Diagnostics API # Introduction This documentation provides information on the Service Diagnostics API and how to access it. Please note: In this document, we use Buyer and Supplier for the Service Provider / CityFibre respectively and Reporter as the person within the Buyers Organisation. This document describes the messages which can pass between Buyer and Supplier, and the various status changes and updates for diagnostic requests though-out the process. # Design Overview See diagram Diagnostic_API_v1.1 for an overview of the flow.
Diagnostic API v1.1
Diagnostic API v1.1
# Accessing the API The API is accessed via HTTPS. Calls are made by POST, sending XML as the HTTP body. Messages are exchanged using SOAP exchanges over HTTPS POST, where the request is in the POST body and the response is in the HTTP response body. Messages are encapsulated in a SOAP envelope using Document/Literal style following WS-Basic Profile 1.0. ```xml ... single request or response element goes here ... ``` ### Integration Environments CityFibre provides two pre-production environments for the Buyer to integrate with, to allow the Buyer to test the API endpoint before going live. ### Authentication Authentication is handled in the same way as the Order API and the authentication details provided apply to this API endpoint. Below are the details for these environments: CFSIT: [https://api-gw.cityfibre.com:41223/cfsit/api2](https://api-gw.cityfibre.com:41223/cfsit/api2) CFStaging: [https://api-gw.cityfibre.com:41223/cfstaging/api2](https://api-gw.cityfibre.com:41223/cfstaging/api2) Production: [https://api-gw.cityfibre.com:41223/prod/api2](https://api-gw.cityfibre.com:41223/prod/api2) License: Apache 2.0 ## Servers Main (production) server ``` https://api-gw.cityfibre.com:41223/prod/api2 ``` CFStaging server ``` https://api-gw.cityfibre.com:41223/cfstaging/api2 ``` CFSit server ``` https://api-gw.cityfibre.com:41223/cfsit/api2 ``` ## Security ### Certificate MutualTLS Certificate Type: mutualTLS ## Download OpenAPI description [CityFibre - Service Diagnostics API](https://service-diagnostics.docs.cityfibre.com/_bundle/openapi.yaml) ## Service Diagnostics The Buyer can request diagnostic information for a serviceId reported in the request. The request will come synchronously and contain the serviceDiagnostic information. The response to a requestServiceDiagnostics call contains the current state of the service and the utilisation status of the network path during the last busy period. ### Request Service Diagnostics - [POST /requestServiceDiagnostics](https://service-diagnostics.docs.cityfibre.com/openapi/service-diagnostics/requestservicediagnostics.md): When the request is received and the ServiceID is validated, the ServiceID is used to Diagnose the network, the found details are then returned to the Supplier in the supplierDiagnostics element of the faultDetails. The details returned are: ONT Status (Status) - Service Up / Service Down - Dying Gasp - Last Date - Time this event was received - The change from the previous state CFM Status (CFM Status) - Up/Down CF/Down ISP - Last Date - Time this event was received - The change from the previous state UniPort Status (Uniport Status) - Up/Down - Last Date - Time this event was received - The change from the previous state Please note – with UniPort Status the Status will continue to show as UP if the ONT Status is DOWN. This is due to the ONT not being able to communicate the UniPort status. In this instance the ONT Status should take priority in the diagnostic analysis. If UniPort Status is blank please use ONT & CFM Status to determine line condition. In conjunction with the diagnostics process, nodes are classified within distinct lists based on their geographical context: - Local Configuration: Identified as ENNI - Interconnect - PON, these nodes signify local network interconnections. - National Configuration: Denoted as Interconnect - Handoff - ENNI - PON, these nodes represent national-level network interconnections. Further, the operational status of these nodes is evaluated and categorized into the following states: Red, Orange, Green, and Unk (for unknown status). For definition the POP is given a RAG status based upon peak loading over 5 minutes during the Busy Period, currently defined in Schedule 1. For the PON, the RAG Status is based upon the peak loading over 15 minutes during the Busy Period currently defined in Schedule 1. For confirmation the RAG status limits are below: Red – 95% or higher Amber – 80% or more to 94% Green – Less than 79% ## XSD File ### Get the XSD for the Service Diagnostics - [GET /serviceDiagnostics.txt](https://service-diagnostics.docs.cityfibre.com/openapi/xsd-file/getservicediagnosticsxsd.md): Download XSD ## Revision History ### Revision history for the Documentation - [GET /changeLog.txt](https://service-diagnostics.docs.cityfibre.com/openapi/revision-history/getrevisionhistory.md): Ten most recent changes made to these docs | Date | Change | |------------|------------------------------------------------------------------------------| | 16/09/2024 | Added NBA (Next Best Action) codes to XSD and the explanations for them | | 25/07/2024 | Removed incidents from currentStatus | | 17/05/2024 | Added the Revision History document | | 18/04/2024 | Added the explanations for UniPort Status values | | 11/04/2024 | Added currentUniportStatus field to the XSD schema | | 03/04/2024 | Added the node utilisation for Local and National Configurations | | 08/03/2024 | Added the explanations for ONT Status and CFM Status values | | 16/02/2024 | Fixed the buyerIdentifier field in the XSD schema | | 15/02/2024 | Added the Service Diagnostic API diagram | | 12/02/2024 | Updated the servicePathUsage field in the XSD schema | | 07/05/2026 | Removed the Next Best Action Fields from the schema | Download full change log here: Download Change Log