Client connections

The Client connections API can be used to retrieve status information of a building in the context of a delayed connection.

Two endpoints for this API exist. Signatures:

GET /api/v1/buildings/{id}/client-connections/

and

GET /api/v1/buildings/client-connections?buildingName={building name}

Examples of use cases:

• Determining whether a specific building is connected.
• Resolving the geo-location of the slack belonging to a to-be-connected building.

Characteristics

Actuality of data

The Client connections API retrieves the information from the Cocon Fiber database. Therefore the actuality of the data is real-time.

Quality of service

The availability of the Client connections API is similar to the other Cocon Fiber API's. Dependent on the type of subscription, specific rate limiting and/or quota measures may be in effect (see the general rate limiting information on the API's overview page).

Filtering and paging

Filtering and paging are not applicable to the Client connections API.

Security

The Client connections API uses system context authentication. See the general information about system context authentication on the API's overview page.

Usage Guidelines

There are certain specifics with regard to the usage of the Client connections API, which are described below.

General usage

Call the Client connections API in order to get the real-time information of a building regarding its delayed connection status.

Example request 1

GET /api/v1/buildings/{id}/client-connections/

Parameters

From query string

• {id}: The building id that uniquely identifies the building (e.g. 1937214). The building type of the building can not be of type 'Complex'

Example request 2

GET /api/v1/buildings/client-connections?buildingName=7523HS-481

Parameters

From query string

• {id}: The name of the building which is a combined string of zipcode with house number (e.g. 7523HS-481).

warning

The building type of the building can not be of type 'Complex'

warning

Responses

When the API returns status code success (200) the delayed connection status of a building returned.

Example of a response regarding a building that has not been connected (yet)

{
  "id": "1937214",
  "name": "7951HA-12",
  "complexName": "NM-ZWANENVELD",
  "frameNames": [
    "7951HA-12 GV"
  ],
  "terminationUnitTypes": [
    "DIVERS"
  ],
  "installationCompanyName": "BAM Infra",
  "cableInformation": [
    {
      "cableReference": {
        "name": "K-7951HA-12",
        "id": "1767888",
        "href": ""
      },
      "endpointReference": {
        "type": "Slack",
        "geometry": {
          "type": "Point",
          "coordinates": [
            210784.9081,
            517504.66085
          ]
        },
        "id": "1767889",
        "href": ""
      },
      "cableTypeReference": {
        "name": "2V_DAC_PM60056100",
        "id": "1767888",
        "href": ""
      },
      "fibers": null
    }
  ]
}

Example of a response regarding a building that has been connected

{
  "id": "1937215",
  "name": "7951HA-14",
  "complexName": null,
  "frameNames": [
    "7951HA-14 MTK"
  ],
  "terminationUnitTypes": [
    "FTU_DK01"
  ],
  "installationCompanyName": "BAM Infra",
  "cableInformation": [
    {
      "cableReference": {
        "name": "K-7951HA-14",
        "id": "1767894",
        "href": ""
      },
      "endpointReference": {
        "type": "Frame",
        "geometry": {
          "type": "Polygon",
          "coordinates": [
            [
              [
                210780.459448936,
                517510.353847848
              ],
              [
                210782.46684073,
                517508.124413348
              ],
              [
                210780.980551064,
                517506.786152152
              ],
              [
                210778.97315927,
                517509.015586652
              ],
              [
                210780.459448936,
                517510.353847848
              ]
            ]
          ]
        },
        "id": "1368475",
        "href": ""
      },
      "cableTypeReference": {
        "name": "2V_DAC_PM60056100",
        "id": "1767894",
        "href": ""
      },
      "fibers": [
        {
          "index": 1,
          "attenuation": 1.436
        },
        {
          "index": 2,
          "attenuation": 1.321
        }
      ]
    }
  ]
}

Error codes

The table below states the possible errors when calling the Cocon Fiber Client connections API:

Error Code	Scope	Error message	Notes
BDG-0001	Building	Building not found	The BuildingId must refer to an existing building

note

See the generic Transactional API documentation for information about Error Responses.