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):
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. 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):
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.
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
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.
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.
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:
Example 2:
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
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
GET/v1/resource/TYPES - Get all available resource types
Curl
Request URL
https://sandbox-api.axonvx.com/api/biz2/v1/resource/TYPES
Server response
Code: 200
Details: Response body
GET/v1/resources/{company_id}/DISCOVER - All the available resources
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
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
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
GET/v1/resource/PROVIDERS - Get all available resource providers
Curl
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
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
Server response
Code: 200
Details: Response body
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
Server response
Code: 200
Details: Response body
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
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
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
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
PUT/v1/service/exc/{service_guid} - Update an EXC service definition
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
DELETE/v1/service/exc/{service_guid} - Delete an EXC service definition
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
DELETE/v1/resource/{resource_guid} - Delete an allocated resource
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
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.