Contents

AXON API Documentation v1.2.5

Sep 5, 2023

 

Introduction

AXON API allows you to accelerate and simplify digital transformation solutions by leveraging NEXTDC’s state-of-the-art hybrid and multi-cloud interconnection platform. 

What is AXON?

NEXTDC’s AXON virtual interconnectivity platform provides advanced Network-as-a-Service (NaaS) functionality orchestrating simpler, more secure and dynamic multi-cloud, hybrid environments.

It enables unprecedented capability to engineer safe, resilient, flexible and self-provisioned unification of data, clouds, locations, service providers and people.

By drastically reducing complexity and costs of interconnection architecture AXON supports direct, point-to-point connectivity services that can be:

· Turned on and off as needed,

· Configured to the appropriate bandwidth required, and

· Billed purely on usage.

Long-term contracts are a thing of the past, insecure public internet cloud connectivity is eliminated, and data can be entirely managed within the one sovereign ecosystem that is supported by the highest levels of resilience and security engineering and operational processes.

 AXON Value 

AXON supports accelerated multi-cloud migration and utilisation via:

  • Complete point-to-point redundancy – AXON is engineered to ensure there are no single points of interconnection failure delivering 100% geo-diverse routes across its virtual fabric mesh. It guarantees that connections will be available between any two points on the network.
  • Ultra-low latency cloud connectivity – When performance is critical, proximity matters. AXON facilitates the shortest possible distances between your physical and virtual infrastructure. Whether you have critical systems and solutions at one of our remote edge DC locations or in our metro-based hyperscale technology hubs, your access to the world’s leading cloud and digital services providers cannot be faster.
  • Connect everything to anywhere – AXON extends to all NEXTDC facilities as well as multiple strategic third-party cloud zones and NEXTDC’s extensive ecosystem of 770-plus clouds, carriers and digital services providers.
  • Security assured – All interconnections contained within a secure and sovereign ecosystem hosted and managed to global and industry best practice standards for physical security
  • Flexibility and agility – Easy, self-provisioned services at the bandwidth required by any authenticated users managed with ease from within the AXON management portal with services going live within minutes
  • Cost-effective connectivity – Once connected to the portal, users only pay for time and bandwidth used under utility billing model. No long-term contracts. One single line-item for all multi-cloud interconnection

 The AXON API Advantage 

AXON virtual connections enable organisations, networks, and cloud providers to orchestrate fast, secure, and dynamic interconnection from any point-of-presence in the NEXTDC ecosystem to any other point on the network including cloud services providers, customers, partners and carriers.

AXON API is now available to cloud migration and digital transformation service providers to integrate into their own solutions or for enterprise-level organisations to extend the reach and functionality of their interconnection solutions.

Accelerate your competitive advantage and transformation journey with AXON API.

Getting Started

Requesting an API key


Please speak to your pre-sales representative to request API access and the process to obtain an API key and sandbox access. You will need to supply an existing AXON user that you wish to grant API access to and the source IP addresses that you will be accessing the API from.

Access to the AXON API

Access to the AXON API is via an API key. An API key, secret and host access list needs to be generated. The key mechanism is similar to what AWS uses for API access. The AXON API requires an increasing, never repeated nonce to guard against replay attacks. We use unix timestamp as the nonce. Due to the nonce increasing and being unique you will need to use a timestamp with millisecond or better resolution.

 

The format of the nonce is as follows (generated by the bash date cli command):

date '+%s.%N'

1651447214.740975533

 

Clients need to ensure that the nonce time is accurate to within 2 minutes of the API server time otherwise authentication will fail. This is to guard against wildly out client times that need adjusting causing the nonce to go backwards.

API key authentication

Pass the api_key in via http header "X-API-Key" and the nonce via http header "X-API-TS". 
 
CLI example 
 
Note the API key is in the format key:digest using the HMAC method and sha256 algorithm. Seehttps://restcookbook.com/Basics/loggingin/for example implementation. 
The digest is calculated against the API method (GET/POST etc), the path (the query parameters are not included) and the nonce. 
 
The digest is not base64 encoded. 
 
Sample CLI test script. The digest data before HMAC is applied is (note no spaces and just the path):

GET/api/biz2/v1/locations

#!/bin/bash

apikey="key"

secret="123"

path="/api/biz2/v1/locations"

param="?location_id=AU-NXT-S1"

uri="https://sandbox-api.axonvx.com$path$param"

method="GET"

nonce=`date '+%s.%N'`

apisig=`printf %s "$method$path$nonce" | openssl dgst -sha256 -hmac "$secret" | sed 's/^.*= //'`

 

echo $apisig

echo

 

curl -X GET $uri -H "accept: application/json" -H "X-API-Key: $apikey:$apisig" -H "X-API-TS: $nonce"

Workflow and usage


To use the AXON API the following workflow is suggested:

  • Use the GET locations call to get a list of the available facilities.
    • The locations call also returns the list of directly connected neighbouring facilities via a metro or fabric-interconnect (intercap).
  • Filter the list of locations (the locations contains AXON connectivity and may include more in future).
  • Use the GET resource types call to get a list of available port or other resource details.
    • This information should be cached (note resources will only be added, never deleted). The information from this call will rarely change.
  • Use the GET resources discover call to get the resource catalogue.
    ○ The key between the available resources and the type details is the resource_type_class field.
  • Use the POST resource call to allocate a port resource by location_id using the resource_type class.
    • Supplying an existing resource GUID will ensure equipment diversity
    • Any additional options available for the resource (obtained from the GET resource types call schema) should be passed in via the resource options object.
  • Use the GET resource providers call to get a list of available providers.
    • This information should be cached and used as the keys into a price book (note infrastructure provider keys will only be added, never deleted). The information from this call will rarely change.
    • The inputs required for a provider are defined by the returned JSON schema.
  • Use the GET services discover call to obtain a list of candidate services and provider chains.
  • Filter the list of candidate services and apply pricing based on the provider chain.
    • Use the GET limitations call to determine bandwidth tiers and maximum available bandwidth
    • If items in the provider chain cannot be priced the entire candidate service should be discarded.
  • Use the selected candidate service ID to call the POST service call to create a service.
    • From the schemas previously obtained from the GET resource providers call obtain the list of required keys to build the product options object.
  • Post resource allocation and service creation various helper API calls are available to obtain resource and service status information.

 

User & company access control

The company access control model in AXON is hierarchical. This means that having access at a specific level in the hierarchy,access flows down to sub-companies. To view your access, use the GET user api call. This will return your user information plus all the companies and roles (access rights) you have with each company. This call will also return the unique company_id for each company which is required for most other API calls. Note that when a company_id is requested this is the buyer company_id, not the B-end service provider company. Any pricing offered and purchase transactions will be raised against this company_id.

{

    "user": {

        "user_login_id": "mylogin",

        "user_email": "My.User@nextdc.com",

        "user_full_name": "My User",

        "user_phone": "0400555555",

        "mfa": 1

    },

    "companies": [

        {

            "company_id": "AU123456",

            "requires_mfa": 0,

            "company_name": "Company 1",

            "company_short_name": "COMPANYONE",

            "user_roles": [

        .

        .

        .

        .
 

Swagger API explorer

AXON API users with a valid API key for the sandbox environment can access the Swagger API Explorer via this link: https://sandbox-api.axonvx.com/swagger-ui/index.html

AXON API users with a valid API key for the sandbox environment can access the Swagger API Explorer via this link: https://sandbox-api.axonvx.com/swagger-ui/index.html

 

Screenshot 2024-02-29 at 2.32.05 pm

 

The AXON API sandbox environment replicates production and simulates a provisioning cycle without actual network interaction. The sandbox is not physically connected to the production network and exists in a different security zone. The sandbox will be reset once a week with fresh production data.

Resources and services

Objects and their relationships

Resources are allocated to a facility and are offered by resource providers. A collection of resources comprise a product or service chain. To find paths through the network from an A-end resource to a provider we call discovery. All the resource providers and permutations used along the path will then be offered as a list of candidate services and priced up. Note that candidate services are transient (only valid for the current user session) as pricing and price books are dynamic. As there may be many ways to reach a B-end provider from an A-end buyers perspective, many candidate services utilising different intermediate resource providers could be offered with different pricing options. It is up to the buyer to determine the best candidate service option to use to ultimately create a service with.

Every resource, service and candidate service is assigned a unique id (GUID).

 

Resource type capabilities

For resources that have multiple capabilities a mode needs to be specified on allocation when using the POST resource call via the resource options object. Provide the required mode via the port_mode key. The list of supported modes or bandwidths for a specific fabric-interconnect is returned by the GET resources discover call.

 

{

    "total": 5,

    "resources": [

        {

            "city": "Sydney",

            "location_id": "AU-NXT-S1",

            "location_description": "NEXTDC S1",

            "country": "AU",

            "resource_type_class": "FI",

            "candidate_resource_guid": "85e44356-fda5-48c7-93c1-3594ad72df64",

            "extra_info": {

                "capabilities": [

                    {

                        "port_mode": "FI-50M",

                        "port_mode_speed": 50000000,

                        "port_mode_descrip": "50Mb Fabric Interconnect"

                    },

                {

                    "port_mode": "FI-100M",

                    "port_mode_speed": 100000000,

                    "port_mode_descrip": "100Mb Fabric Interconnect"

                },

                .

                .

                .

 

Important details to note:

  • All speeds and bandwidths are in bps (bit per second).
  • Only 802.1Q handoffs are supported.
  • Valid VLAN ranges are between 2 and 3999.
  • Results that have a "total" key shows the total number of rows in the result-set irrespective of any paging.
  • Cross connects (xconnect), DCIe and DCIf cannot be ordered through the AXON API.

 

AXON locations

To get a list of the AXON points of presence, use the GET locations call. The location_id references the facility in which a resource resides. When querying services the service chain will show all the facilities traversed. Protected parts of the service will not be show.

Below is an example of a location definition. All location_id's in the same city can be assumed to be on the same local metro. The neigbors key defines the directly reachable neighboring facilities via AXON fabric interconnect (Intercap).


The location_id is encoded as "country -dc_provider -facility_code" and each code is unique.

{
  "total": 32,
  "locations": [
    {
      "location_id": "AU-NXT-B1",
      "description": "NEXTDC B1",
      "country": "AU",
      "city": "Brisbane",
      "neighbors": [
        "AU-NXT-B2",
        "AU-NXT-S1",
        "AU-NXT-S2",
        "AU-NXT-P1",
        "AU-NXT-M1",
        "AU-NXT-C1",
        "AU-NXT-SC1"
      ]
    },
.

.

.

 

Intercap

The following workflow is suggested:

  • Use the GET resources discover call to get the resource catalogue.
    • Filter by resource_type_class of fi to get the available fabric-interconnects for a metro
    • The neighbour_location_id for each fabric-interconnect designates adjacency. Use the GET locations call to see what other locations are then indirectly reachable via this fabric-interconnect
  • Use the POST resource call to allocate the desired fabric-interconnect and bandwidth required
    • The POST call requires the candidate_resource_guid for the desired fabric-interconnect to be supplied and the bandwidth is set via the port_mode key

HTTP Responses and codes


The following HTTP response codes are used:

Code

Description Comments

200

Ok The request was actioned, but depending on the type of request may be provisioned in the background. The service provisioning status will need to be periodically checked for completion. The provisioning may still fail due to a downstream provider experiencing an error.
202 Accepted  Requests that have a manual component or remote end acceptance or some form of negotiation required. The service provisioning status will need to be periodically checked for completion.
400 Bad Request  
401 Unauthorized  
403 Forbidden  
404  Not Found  
409  Conflict Will occur on any duplicate, for example a duplicate VLAN

 

Status codes

For service and resources the following status codes are used for the provisioned or deprovisioned state. For services, each provider sequence or hop in the chain has its own status code.

Code

Description

S

Scheduled for provisioning or deprovisioning

U

Updating

C

Completed provisioning (ready for service) or deprovisioning (removed off the network)

H

Holding (when waiting on additional input from a provider)

M

Manual Deprovision / Update (when a provider requires manual involvement)

R

Retry (provisioning or deprovisioning failed and is retrying)

F

Failed (provisioning or deprovisioning exceeded the retry count and has given up)

D

Deprovisioning requested

Examples:

  • provisioned = S, deprovisioned = N : scheduled for provisioning
  • provisioned = D, deprovisioned = S : scheduled for deprovisioning
  • provisioned = C, deprovisioned = N : ready for service
  • provisioned = R, deprovisioned = N : scheduled for provisioning, but retrying due to failure
  • provisioned = M, deprovisioned = N : deleting will cause state to change to H and operations will be notified
  • provisioned = F, deprovisioned = N : provisioning failed - see GET service/exc/{service_guid}/INFO call for error reasons
  • provisioned = D, deprovisioned = F : deprovisioning failed - see GET service/exc/{service_guid}/INFO call for error reasons

 

Timestamps

 

All timestamps are in ISO8601 format without millisecond precision and could be in any timezone. The API caller should convert timestamps to a desired local timezone. If required, timestamps can be returned in another timezone by passing in a "tz" query parameter with a request, for example tz=AEDT. Valid ISO timezone abbreviations are defined here: List of tz database time zones - Wikipedia

 

 

Schemas

The GET resource providers and GET resource types calls return a JSON schema. The schema defines the mandatory and optional keys required for the product_options or resource_options objects when building a new service or allocating a resource. These schemas can change, and new schemas will appear when providers are added, so it is important to utilise and validate against the schema.

 

NOTE: the schemas only contain basic information currently (see https://json-schema.org/learn/getting-started-step-by-step.html#starting). These annotations will be updated over time and could be used as the titles and descriptions for input forms.

 

Sample provider definitions

 Example 1

    {
      "type": "microsoft",
      "description": "MSFT cloud",
      "class": "cloud",
      "scope": "node",
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "$id": "https://sandbox-api.axonvx.com/api/biz2/v1/schema/Azure-provider.schema.json",
        "type": "object",
        "title": "Azure Provider Schema",
        "required": [
          "skey"
        ],
        "properties": {
          "skey": {
            "$ref": "definitions/Azure.schema.json#/definitions/skey"
          },
          "selective_qinq": {
            "$ref": "definitions/Service.schema.json#/definitions/selective_qinq"
          }
        }
      }
    },

 

Example 2:

    },
    {
      "type": "oob:axon",
      "description": "Out of band via AXON",
      "class": "service",
      "scope": "port",
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "$id": "https://sandbox-api.axonvx.com/api/biz2/v1/schema/Oob-provider.schema.json",
        "type": "object",
        "title": "Oob Provider Schema",
        "required": [
          "bandwidth_cir"
        ],
        "properties": {
          "bandwidth_cir": {
            "$ref": "definitions/Service.schema.json#/definitions/bandwidth_cir"
          }
        }
      }
    }

  

 

 

Schema specifications

Currently we use JSON schema draft-07. See Specification | JSON Schema (json-schema.org)

AXON will move to draft-2020-12 to be aligned with OpenAPI v3.1, see Migrating from OpenAPI 3.0 to 3.1.0 - OpenAPI Initiative (openapis.org)

 

 

 

Examples 


Below is an example of a typical workflow described in the 'Workflow and usage' section. Not all service permutations are currently described in this document. To get more detail about AXON service offerings see https://www.nextdc.com/customer-support/connectivity

At a high-level the below examples describe:

  • Getting all the AXON locations
  • Getting the resource catalogue
  • Allocating a resource from the catalogue
  • Getting the available services from the allocated resource
  • Creating a new service
  • Removing the service
  • Removing the resource

Note that any links below are against the sandbox environment and Swagger API Explorer interface and will be different for production.


GET/v1/locations - List locations

Curl

curl -X 'GET' \ 

  'https://sandbox-api.axonvx.com/api/biz2/v1/locations' \ 

  -H 'accept: application/json' \ 

  -H 'X-API-Key: key:digest' \ 

  -H 'X-API-TS: 1652153033.884'


Request URL

https://sandbox-api.axonvx.com/api/biz2/v1/locations

Server response

Code: 200     
Details: Response body

{
  "total": 32,
  "locations": [
    {
      "location_id": "AU-NXT-B1",
      "description": "NEXTDC B1",
      "country": "AU",
      "city": "Brisbane",
      "neighbors": [
        "AU-NXT-B2",
        "AU-NXT-S1",
        "AU-NXT-S2",
        "AU-NXT-P1",
        "AU-NXT-M1",
        "AU-NXT-C1",
        "AU-NXT-SC1"
      ]
    },
.

.

.

 


From https://sandbox-api.axonvx.com/swagger-ui/index.html#/locations/bizApiLocationLocationsBiz

GET/v1/resource/TYPES - Get all available resource types

Curl

curl -X 'GET' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/resource/TYPES' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652153371.582'


Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/TYPES

Server response
Code: 200     
Details: Response body

    {
      "type": "40GBASELRL4",
      "description": "Single mode optical - up to 1km (for use within datacentre)",
      "class": "40GBASELRL4",
      "scope": "port",
      "extra_info": {
        "specifications": {
          "connector_type": "LC",
          "cable_type": "SMF",
          "wavelength": {
            "unit": "nm",
            "min": 1271,
            "max": 1331
          },
          "tx_power": {
            "unit": "dBm",
            "min": "-7.0",
            "max": "2.3"
          },
          "rx_power": {
            "unit": "dBm",
            "min": "-11.5",
            "max": "2.3"
          },
          "operating_distance": {
            "unit": "km",

.

.

.


From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceRetrieveResourceAvailableTypesBiz

GET/v1/resources/{company_id}/DISCOVER - All the available resources

Curl

curl -X 'GET' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/resources/DEMOCO/DISCOVER' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652153458.42'

 

Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resources/DEMOCO/DISCOVER

Server response
Code: 200     
Details: Response body

{
  "total": 80,
  "resources": [
    {
      "location_id": "AU-NXT-B1",
      "resource_type_class": "10GBASELRL",
      "resource_speed": 10000000000,
.

.

.
      "skus": [
        {
          "sku_code": "AXON-PORT-10G-LRL",
          "sku_descrip": "10GBASE-LRL - Up to 1km",
          "contract_term": 1,
          "volume": 0,
          "install_fee": "yyy.00",
          "unit_price": "xxx.00"
        },
        {
          "sku_code": "AXON-PORT-10G-LRL",
          "sku_descrip": "10GBASE-LRL - Up to 1km",
          "contract_term": 12,
          "volume": 0,
          "install_fee": "0.00",
          "unit_price": "xxx.00"
        }
      ]
    },

.

.

.

 

From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resources/bizApiResourceResourceDiscoverBiz

POST/v1/resource/{company_id} - Allocate the next available resource

 

For purchase operations a double POST is required. The first POST accepts the input and returns a set of documents that need to be signed. To sign the documents, take the document ID's from the response and add them to the original request as an array. If the second call is successful an array of resources will be returned. 

Any required or optional keys as per the resources schema should be added to the resource_options object. 


Curl

curl -X 'POST' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/resource/DEMOCO' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652154307.305' \
  -d '{
  "location_id": "AU-NXT-S1",
  "resource_type_class": "10GBASELRL",

  "resource_options": {

    "description": "My first port label",

    "provider": "public",
    "resource_advertisement": "My first port public description"

  },
  "contract_term": 12
}'



Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/DEMOCO

Server response
Code: 200     
Details: Response body
 

{
  "documents": [
    {
      "document_id": "TCGEN0001.01647836398.QVhPTlZYIFN0YW5kYXJkIFRlcm1zLm1k",
      "content_type": "Content-type: text/markdown",
      "document_title": "AXON Standard Terms & Conditions",
      "body_base64": "IyBUZXJtcyBhbmQgQ29uZGl0aW9ucwotICoqM

.

.

.



From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceAllocateResourceBiz

Curl

curl -X 'POST' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/resource/DEMOCO' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652154403.425' \
  -d '{

  "location_id": "AU-NXT-S1",
  "resource_type_class": "10GBASELRL",

  "resource_options": {

    "description": "My first port label",

    "provider": "public",
    "resource_advertisement": "My first port public description"

  },
  "contract_term": 12,

  "document_ids": ["TCGEN0001.01647836398.QVhPTlZYIFN0YW5kYXJkIFRlcm1zLm1k"]
}'



Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/DEMOCO

Server response
Code: 200     
Details: Response body

{
  "resources": [
    {
      "resource_guid": "f54326cd-b100-4563-90fc-9f7f473dba19",
      "description": "My first port label",
      "location_id": "AU-NXT-S1",
      "meetme": "S1-IR2-EE05-A Port 9/10"
    }
  ]
}



From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceAllocateResourceBiz


GET/v1/resource/PROVIDERS - Get all available resource providers

Curl

curl -X 'GET' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/resource/PROVIDERS' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652154684.961'


Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/PROVIDERS

 

Server response
Code: 200     
Details: Response body

{
  "providers": [
    {
      "type": "microsoft",
      "description": "MSFT cloud",
      "class": "cloud",
      "scope": "node",
      "schema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "$id": "https://sandbox-api.axonvx.com/api/biz2/v1/schema/Azure-provider.schema.json",
        "type": "object",
        "title": "Azure Provider Schema",
        "required": [
          "skey"
        ],
        "properties": {
          "skey": {
            "$ref": "definitions/Azure.schema.json#/definitions/skey"
          },
          "selective_qinq": {
            "$ref": "definitions/Service.schema.json#/definitions/selective_qinq"
          }
        }
      }
    },

.

.

.



From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceAvailableProvidersBiz


GET/v1/services/{company_id}/{resource_guid}/DISCOVER - All services reachable from GUID

 

This call returns all the possible services and paths from a source resource (including pricing). This is the first part before service creation allowing API consumers to view the catalogue. Each candidate is assigned a one-time GUID which is used during any subsequent service creation POST request. All the providers that comprise the service will appear in the provider chain ordered from A-end (generally a source port) to the destination (generally a B-end port or cloud provider). For service candidates that have volume based pricing multiple candidate GUID's will be returned. 

In the below example the service_type denotes the B-end provider and the diversity_index denotes the B-end providers egress points for their service. For example where a cloud provider has a primary, secondary and tertiary path the indexes would be 0, 1 and 2. 



Curl

curl -X 'GET' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/services/DEMOCO/f54326cd-b100-4563-90fc-9f7f473dba19/DISCOVER?provider=aws' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652154828.131'


Request URL

https://sandbox-api.axonvx.com/api/biz2/v1/services/DEMOCO/f54326cd-b100-4563-90fc-9f7f473dba19/DISCOVER?provider=aws


Server response
Code: 200     
Details: Response body

{
  "candidate_services": [
    {
      "candidate_service_guid": "ebca2140-31ec-4bd8-bc5c-cfc1719711e4",
      "candidate_service_description": "Amazon Web Services (AWS) NEXTDC S2, Sydney: Secondary node",
      "service_type": "aws",
      "diversity_index": 1,
      "company_name": "Amazon Web Services (AWS) NEXTDC S2, Sydney",
      "location_id": "AU-NXT-S2",
      "provider_chain": [
      {
          "provider": "public",
          "location_id": "AU-NXT-S1"
        },
        {
          "provider": "fabric",
          "location_id": "AU-NXT-S1"
        },
        {
          "provider": "fabric",
          "location_id": "AU-NXT-S2"
        },
        {
          "provider": "aws",
          "location_id": "AU-NXT-S2"
        }
      ],

      "sku": {
        "sku_code": "AXON-CLOUD-AWS",
        "sku_descrip": "Amazon Direct Connect Connection",
        "contract_term": 0,
        "volume": 0,
        "install_fee": "0.00",
        "unit_price": "xxx.00"
      }
    },

.

.

.



From https://sandbox-api.axonvx.com/swagger-ui/index.html#/services/bizApiServiceServicesDiscoverBiz

 

GET/v1/limitations/{type}/{guid} - Get Limitations of a GUID

 

The limitations call returns all the possible service bandwidth permutations. Only the specified bandwidths will be accepted for a given candidate service as per the previous discovery process and GUID. Bandwidths are determined by the allowed bandwidths as specified by all the service providers along the service path. 

The limitations call should again be used for any subsequent update operations. 



Curl

curl -X 'GET' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/limitations/candidateservice/ebca2140-31ec-4bd8-bc5c-cfc1719711e4' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652158953.638'

 

Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/limitations/candidateservice/ebca2140-31ec-4bd8-bc5c-cfc1719711e4

Server response
Code: 200     
Details: Response body

{
  "allowed_bandwidths": {
    "bandwidths": [
      50000000,
      100000000,
      200000000,
      300000000,
      400000000,
      500000000,
      1000000000,
      2000000000
    ]
  },
  "limitations": [
    {
      "provider": "aws",
      "maximum_bandwidth": 10000000000
    }
  ]
}



From https://sandbox-api.axonvx.com/swagger-ui/index.html#/limitations/bizApiLimitationsRetrieveLimitationsBiz

 


POST/v1/service/exc/{company_id} - Create an EXC service from a service definition

For purchase operations a double POST is required. The first POST accepts the input and returns a set of documents that need to be signed. To sign the documents, take the document ID's from the response and add them to the original request as an array. If the second call is successful an array of resources will be returned. 
 
When creating a new service the product_options object needs to contain all the required key value pairs as per the provider_chain returned during the service discovery phase. The JSON schemas in the GET/v1/resource/PROVIDERS call define all the key value pairs for each of the providers. The product_options will be a union of all the required keys.

Curl

curl -X 'POST' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/DEMOCO' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652155133.664' \
  -d '{
  "candidate_service_guid": "ebca2140-31ec-4bd8-bc5c-cfc1719711e4",
  "product_options": {
    "description": "My first service",
    "outer_vlan": 222,
    "bandwidth_cir": 200000000
  }
}'

 

Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/DEMOCO

Server response
Code: 200     
Details: Response body

{
  "documents": [
    {
      "document_id": "TCGEN0001.01647836398.QVhPTlZYIFN0YW5kYXJkIFRlcm1zLm1k",
      "content_type": "Content-type: text/markdown",
      "document_title": "AXON Standard Terms & Conditions",
      "body_base64": "IyBUZXJtcyBhbmQgQ29uZGl0aW9ucwot

.

.

.



From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceServiceCreateBiz


Curl

 

curl -X 'POST' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/DEMOCO' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652155250.439' \
  -d '{
  "candidate_service_guid": "ebca2140-31ec-4bd8-bc5c-cfc1719711e4",
  "product_options": {
    "description": "My first service",
    "outer_vlan": 222,
    "bandwidth_cir": 200000000,
    "aws_account_id": "123456789012"
  },
  "document_ids": ["TCGEN0001.01647836398.QVhPTlZYIFN0YW5kYXJkIFRlcm1zLm1k"]
}'

 

Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/DEMOCO

Server response
Code: 200     
Details: Response body

{
  "service_id": "4a20a793-c84b-40ee-affe-cd90d3d5989c"
}



From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceServiceCreateBiz

 

GET/v1/service/{service_guid} - Get a single service

After a service has been accepted for creation via the POST service call the service will provision asynchronously. The initial state of the service chain hops will be "S" for scheduled to provision. As the provisioning operations are completed the provisioned states will change to "C" for completed. When all the sequences are provisioned the service will be ready. 
 
In the event of a failure the state will be "R" for retry. If the retry fails the state will change to "F" for failed. You can use the GET/v1/service/exc/{service_guid}/INFO call to obtain the reason for failure. 

 
Curl

curl -X 'GET' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/service/4a20a793-c84b-40ee-affe-cd90d3d5989c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652155331.81'


 
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/service/4a20a793-c84b-40ee-affe-cd90d3d5989c

Server response
Code: 200     
Details: Response body

curl -X 'GET' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/service/4a20a793-c84b-40ee-affe-cd90d3d5989c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652155331.81'


From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceServiceBiz

 

PUT/v1/service/exc/{service_guid} - Update an EXC service definition

Only the HTTP response code is returned.

Curl

curl -X 'PUT' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/4a20a793-c84b-40ee-affe-cd90d3d5989c' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652232339.444' \
  -d '{
  "outer_vlan": 333
}'


Request URL

https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/4a20a793-c84b-40ee-affe-cd90d3d5989c

From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceServiceUpdateBiz

 


DELETE/v1/service/exc/{service_guid} - Delete an EXC service definition


Only the HTTP response code is returned.

Curl

curl -X 'DELETE' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/4a20a793-c84b-40ee-affe-cd90d3d5989c' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652232461.153'

 

Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/4a20a793-c84b-40ee-affe-cd90d3d5989c

From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceRemoveServiceBiz

 

DELETE/v1/resource/{resource_guid} - Delete an allocated resource

Only the HTTP response code is returned.

Curl

curl -X 'DELETE' \
  'https://sandbox-api.axonvx.com/api/biz2/v1/resource/f54326cd-b100-4563-90fc-9f7f473dba19' \
  -H 'accept: application/json' \
  -H 'X-API-Key: key:digest' \
  -H 'X-API-TS: 1652232605.026'

 

Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/f54326cd-b100-4563-90fc-9f7f473dba19

From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceUnallocateResourceBiz

 

Release notes

 

Known issues

 

There are a couple of caveats to look out for which will be resolved in future:

  • Some HTTP response codes are not correct (example 400 vs 404). 

 

Schema definitions are not complete and will be adjusted over time.