Skip to content

Use Cases

Use the DEMO API

To get familiar with the API, you can use the DEMO API for testing purposes. The DEMO API is a sandbox environment that allows you to test the API without getting extra charges.

Please note: The DEMO API is a separate environment and does not contain or create real data. E.g. the Open Access IDs generated there are only valid in the Demo API.

Assume we are a company enabling end customers to access the internet by open net fiber. We act as a PIP named "fiberpark" and have business relations to two ANOs.

The active network operators (ANO) in the example are (for sake of simplicity) named "fiberano1" and "fiberano2".

Example Setup

Suppose we (as a PIP) would like to pull 5 OAIDs, set coordinates on the OAIDs, and store the corresponding PIP - ANO relations.

The 5 OAIDs should be assigned to the ANOs as follows:

  • 2 OAIDs to "fiberano1"
  • 2 OAIDs to "fiberano2"
  • 1 OAID to both

Here, we demonstrate how the entire process should be completed for each use case.

Create OAID

First, request the 5 OAIDs with the "Create OAID" endpoint. Below is the request and response for pulling an OAID.

$ curl --request POST "https://api.oaid.at/v2/pip/codes/" \
$  --header "Authorization: Bearer <access_token>" \
$  --header "Accept: application/json" \
$  --header "Content-Type: application/json" \
$  --data '{"customer_reference": "loc01212-2442346"}'
---> 100%

{
    "oaid": "ABCD1234",
    "version": "v8",
    "customer_reference": "loc01212-2442346",
    "status": "active",
    "token": "requested",
    "created_at": "2019-05-29T17:11:14.206+00:00"
}

Repeat this request from the endpoint until all five OAIDs have been pulled. The list of all 5 OAIDs may be retrieved later using the "List OAIDs" endpoint.

As we plan on storing location information on each OAID, we do not need to explicitly confirm the OAIDs. This is done implicitly through any subsequent action on the OAID.

Automatic OAID Confirmation (when storing additional attributes)

If you intend to store additional attributes on your OAID (such as coordinates), you don't need to use the PATCH method "Set OAID Attributes" to confirm the OAID. When you call "Assign/Create Site" with an OAID, the token for the OAID will automatically be confirmed for you!

Sync Relations

The next step is to define the PIP-ANO relations in the system by creating a unique relation name for each.

In our example, the PIP named "fiberpark" has new relations with two ANOs: "fiberano1" & "fiberano2". Each relation is created using the "Create Infra Relation" endpoint.

flowchart 
    pip([pip: fiberpark])
    ano1([ano1: fiberano1])
    ano2([ano2: fiberano2])
    pip -->|relation: fiberano1-fiberpark| ano1
    pip -->|relation: fiberano2-fiberpark| ano2
The fields used to define both relations are specified in the collapsible boxes.

Relation to fiberano1
partner company_name rtr_agg_id phone email_to pip_code
ano_code
pip Fiberpark GmbH 400 +43-1-987654321 support@fiberpark-domain fiberpark
ano Fiber ANO One GmbH 401 +43-1-123456789 support@ano1-domain fiberano1 
{
  "pip": {
      "pip_code": "fiberpark",
      "company_name": "Fiberpark GmbH",
      "rtr_agg_id": 400,
      "phone": "+43-1-987654321",
      "email_to": "support@fiberpark-domain.at"
  },
  "ano": {
      "ano_code": "fiberano1",
      "company_name": "Fiber ANO One GmbH",
      "rtr_agg_id": 401,
      "phone": "+43-1-123456789",
      "email_to": "support@ano1-domain.at"
  },
  "reference_url": "https://httpbin.org/get?oaid={oaid}&center={center}&customer_reference={customer_reference}&pip_code={pip_code}"
}
Relation to fiberano2
partner company_name rtr_agg_id phone email_to pip_code
ano_code
pip Fiberpark GmbH 400 +43-1-987654321 support@fiberpark-domain fiberpark
ano Fiber ANO Two GmbH 402 +43-1-123456780 support@ano2-domain fiberano2 
{
  "pip": {
      "pip_code": "fiberpark",
      "company_name": "Fiberpark GmbH",
      "rtr_agg_id": 400,
      "phone": "+43-1-987654321",
      "email_to": "support@fiberpark-domain.at",
  },
  "ano": {
      "ano_code": "fiberano2",
      "company_name": "Fiber ANO Two GmbH",
      "rtr_agg_id": 402,
      "phone": "+43-1-123456780",
      "email_to": "support@ano2-domain.at"
  },
  "reference_url": "https://httpbin.org/get?oaid={oaid}&center={center}&customer_reference={customer_reference}&pip_code={pip_code}"
}

To create the relation between "fiberpark" and "fiberano1":

  1. Create a unique relation name in the path parameter, e.g., fiberano1-fiberpark.

  2. In the request body, enter your business information for "pip" and "ano"

  3. You may additionally request a dynamic URL ("reference_url") in the request body for retrieving information on an OAID: 

    "reference_url": "https://httpbin.org/get?oaid={oaid}&center={center}&customer_reference={customer_reference}&pip_code={pip_code}"

    Reference URL

    Use the placeholders {oaid}, {center}, {customer_reference}, and {pip_code} in the URL to create dynamic links. This can be useful if you want to provide dynamic content (e.g. the link to an OAID's details page).

In full, the request and expected response to create the relation named fiberano1-fiberpark appears as follows:

$ curl --request PUT "https://api.oaid.at/v2/pip/relations/fiberano1-fiberpark/" \
$    --header "Authorization: Bearer <access_token>" \
$    --header "Accept: application/json" \
$    --header "Content-Type: application/json" \
$    --data '{
   "pip": {
      "pip_code": "fiberpark",
      "company_name": "Fiberpark GmbH",
      "rtr_agg_id": 400, 
      "phone": "+43-1-987654321", 
      "email_to": "support@fiberpark-domain.at"
    },
   "ano": {
      "ano_code": "fiberano1",
      "company_name": "Fiber ANO One GmbH",
      "rtr_agg_id": 401,
      "phone": "+43-1-123456789",
      "email_to": "support@ano1-domain.at"
   },
   "reference_url": "https://httpbin.org/get?oaid={oaid}&center={center}&customer_reference={customer_reference}&pip_code={pip_code}"
}'
---> 100%
{
    "relation_name": "fiberano1-fiberpark",
    "tenant": "myfiber",
    "status": "active",
    "pip": {
            "pip_code": "fiberpark",
            "company_name": "Fiberpark GmbH",
            "rtr_agg_id": 400, 
            "phone": "+43-1-987654321", 
            "email_to": "support@fiberpark-domain.at"
    },
    "ano": {
            "ano_code": "fiberano1",
            "company_name": "Fiber ANO One GmbH",
            "rtr_agg_id": 401,
            "phone": "+43-1-123456789",
            "email_to": "support@ano1-domain.at"
    },
    "reference_url": "https://httpbin.org/get?oaid={oaid}&center={center}&customer_reference={customer_reference}&pip_code={pip_code}",
    "created_at": "2019-05-29T17:11:14.206+00:00",
    "modified_at": "2021-04-12T13:03:07.566+00:00"
}

Repeat the procedure above to create the relation between "fiberpark" and "fiberano2".

Sync Customer Sites

After creating the OAIDs and setting up the PIP-ANO relations, the next step is to add location attributes to each OAID using the "Assign/Create Site" endpoint.

Given our example we want to assign the OAIDs as follows:

flowchart 
    ano1([ano1: fiberano1])
    ano2([ano2: fiberano2])
    oaid1([oaid: ABCD1234])
    oaid2([oaid: DCBA4321])
    oaid3([oaid: EFGH4567])
    oaid4([oaid: HGFE7654])
    oaid5([oaid: JKLM9876])
    ano1 -->|operates| oaid1 & oaid2 & oaid5
    ano2 -->|operates| oaid3 & oaid4 & oaid5

To assign a customer site to an OAID:

  1. Specify the OAID in the path parameter.

  2. Enter at a minimum the following required data in the request body:

    • "token": set to "construction" or "operational"
    • "relation_names": list of one or more relations involved
    • "center": the coordinates

The request body for each customer site request are provided below. We assume that all the OAIDs are located in Vienna at Stephansplatz. Therefore, the "center" coordinate, "address", and "address_reference" attributes used in the examples are always the same.

Assigning 2 OAIDs to fiberano1 
{
    "token": "construction", 
    "relation_names": [
        "fiberano1-fiberpark"
    ],
    "center": "48.20854733,16.37295900",
    "address": {
        "country": "AT",
        "zip": "1010",
        "city": "Wien",
        "street": "Stephansplatz"
    },
    "address_reference": {
        "agwr_adr": "7654321-001",
        "agwr_obj": "0006543",
        "usr": "sdf-245-q3e"
    }
}

{
    "token": "operational", 
    "relation_names": [
        "fiberano1-fiberpark"
    ],
    "center": "48.20854733,16.37295900",
    "address": {
        "country": "AT",
        "zip": "1010",
        "city": "Wien",
        "street": "Stephansplatz"
    },
    "address_reference": {
        "agwr_adr": "7654321-001",
        "agwr_obj": "0006543",
        "usr": "sdf-245-q3e"
    }
}
Assigning 2 OAIDs to fiberano2 
{
    "token": "construction", 
    "relation_names": [
        "fiberano2-fiberpark"
    ],
    "center": "48.20854733,16.37295900",
    "address": {
        "country": "AT",
        "zip": "1010",
        "city": "Wien",
        "street": "Stephansplatz"
    },
    "address_reference": {
        "agwr_adr": "7654321-001",
        "agwr_obj": "0006543",
        "usr": "sdf-245-q3e"
    }
}

{
    "token": "construction", 
    "relation_names": [
        "fiberano2-fiberpark"
    ],
    "center": "48.20854733,16.37295900",
    "address": {
        "country": "AT",
        "zip": "1010",
        "city": "Wien",
        "street": "Stephansplatz"
    },
    "address_reference": {
        "agwr_adr": "7654321-001",
        "agwr_obj": "0006543",
        "usr": "sdf-245-q3e"
    }
}
Assigning 1 OAID to fiberano1 & fiberano2 
{
    "token": "construction", 
    "relation_names": [
        "fiberano1-fiberpark",
        "fiberano2-fiberpark"
    ],
    "center": "48.20854733,16.37295900",
    "address": {
        "country": "AT",
        "zip": "1010",
        "city": "Wien",
        "street": "Stephansplatz"
    },
    "address_reference": {
        "agwr_adr": "7654321-001",
        "agwr_obj": "0006543",
        "usr": "sdf-245-q3e"
    }
}
Creating a customer site for fiberano1

Example:

  • ANO: "fiberano1"
  • Relation Name: ["fiberano1-fiberpark"]
  • OAID: "ABCD1234"

Info

The following request and response are for example purpose only, so the values are not real, and might differ when you use the API yourself.

e.g. the lot_id or created_at will very likely differ.

  1. Specify the OAID in the path parameter:

    request PUT "https://api.oaid.at/v2/pip/sites/ABCD1234/"

  2. In the request body, specify the following details (mandatory ones in bold, optional ones in italics):

    • 'token': "construction"
    • 'relation_names': ["fiberano1-fiberpark"]
    • 'center': the coordinates
    • 'address': the address details
    • 'address_reference': the address reference details

    The full list of params can be found in the API docs

$ curl --request PUT "https://api.oaid.at/v2/pip/sites/ABCD1234/" \
$  --header "Authorization: Bearer <access_token>" \
$  --header "Accept: application/json" \
$  --header "Content-Type: application/json" \
$  --data '{
    "token": "construction", 
    "relation_names": [
        "fiberano1-fiberpark"
    ],
    "center": "48.20854733,16.37295900",
    "address": {
        "country": "AT",
        "zip": "1010",
        "city": "Wien",
        "street": "Stephansplatz"
    },
    "address_reference": {
        "agwr_adr": "7654321-001",
        "agwr_obj": "0006543",
        "usr": "sdf-245-q3e"
    }
}'
---> 100%
{
    "oaid": "ABCD1234",
    "customer_reference": "loc01212-2442346",
    "token": "construction",
    "relation_names": [
        "fiberano1-fiberpark"
    ],
    "status": "active",
    "address_reference": {
         "usr": "sdf-245-q3e",
         "agwr_adr": "7654321-001",
         "agwr_obj": "0006543",
         "pac": null
    },
    "address": {
        "country": "AT",
        "zip": "1010",
        "city": "Wien",
        "street": "Stephansplatz",
        "hnr": null,
        "door": null,
        "addon": null
    },
    "lot_id": "04321:16/2",
    "center": "48.20854733,16.37295900",
    "created_at": "2019-05-29T17:11:14.206+00:00",
    "modified_at": "2021-04-12T13:03:07.566+00:00"
}

Read Customer Site

Once the OAID and the relation data have been linked to a customer site, its associated data can be retrieved using the "Read Customer Site" endpoint. The OAID is called in the request within the base URL as a path parameter.

The relation data is presented in the response within the "partners" attribute. This contains the "pip", "ano", and "reference_url" data that was stored with the PUT "Create Infra Relation" endpoint. The reference URL is displayed under the attribute "pip_url" with the corresponding site's data replacing the placeholders set within the relation layer.

To see this in action, let's read the site from the last example:

$ curl --request GET "https://api.oaid.at/v2/pip/sites/ABCD1234/" \
$  --header "Authorization: Bearer <access_token>" \
$  --header "Accept: application/json" 
---> 100%
{
  "oaid": "ABCD1234",
  "customer_reference": "loc01212-2442346",
  "token": "construction",
  "relation_names": [
      "fiberano1-fiberpark"
  ],
  "status": "active",
  "address_reference": {
      "usr": "sdf-245-q3e",
      "agwr_adr": "7654321-001",
      "agwr_obj": "0006543",
      "pac": null
  },
  "address": {
      "country": "AT",
      "zip": "1010",
      "city": "Wien",
      "street": "Stephansplatz",
      "hnr": null,
      "door": null,
      "addon": null
  },
  "lot_id": "04321:16/2",
  "center": "48.20854733,16.37295900",
  "created_at": "2019-05-29T17:11:14.206+00:00",
  "modified_at": "2021-04-12T13:03:07.566+00:00",
  "partners": [
      {
         "relation_name": "fiberano1-fiberpark",
         "pip": {
               "company_name": "Fiberpark GmbH",
               "rtr_agg_id": 400, 
               "phone": "+43-1-987654321", 
               "email_to": "support@fiberpark-domain.at", 
               "pip_code": "fiberpark"
         },
         "ano": {
               "company_name": "Fiber ANO One GmbH",
               "rtr_agg_id": 401,
               "phone": "+43-1-123456789",
               "email_to": "support@ano1-domain.at",
               "ano_code": "fiberano1"
         },
         "pip_url": "https://httpbin.org/get?oaid=ABCD1234&center=48.20854733,16.37295900&customer_reference=loc01212-2442346&pip_code=fiberpark"
      }
  ]
}