Sep 5, 2023
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.
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 supports accelerated multi-cloud migration and utilisation via:
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.
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 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):
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.
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. See https://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):
To use the AXON API the following workflow is suggested:
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.
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
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 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).
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.
Important details to note:
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.
The following workflow is suggested:
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 |
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:
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
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.
Example 1:
Example 2:
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)
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:
Note that any links below are against the sandbox environment and Swagger API Explorer interface and will be different for production.
Curl
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/locations
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/locations/bizApiLocationLocationsBiz
Curl
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/TYPES
Server response
Code: 200
Details: Response body
Curl
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resources/DEMOCO/DISCOVER
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resources/bizApiResourceResourceDiscoverBiz
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
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/DEMOCO
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceAllocateResourceBiz
Curl
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/DEMOCO
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceAllocateResourceBiz
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/PROVIDERS
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/resource/bizApiResourceAvailableProvidersBiz
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
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/services/bizApiServiceServicesDiscoverBiz
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
Server response
Code: 200
Details: Response body
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
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/DEMOCO
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceServiceCreateBiz
Curl
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/service/exc/DEMOCO
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceServiceCreateBiz
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
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/service/4a20a793-c84b-40ee-affe-cd90d3d5989c
Server response
Code: 200
Details: Response body
From https://sandbox-api.axonvx.com/swagger-ui/index.html#/service/bizApiServiceServiceBiz
Only the HTTP response code is returned.
Curl
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
Only the HTTP response code is returned.
Curl
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
Only the HTTP response code is returned.
Curl
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
There are a couple of caveats to look out for which will be resolved in future:
Schema definitions are not complete and will be adjusted over time.