In order to use IX-API, you need to have an account with the Internet Exchange. This can either be your own existing account (created by the IXP), or if you order on behalf of a sub-customer, you can create it yourself, using the accounts_create operation.

Fill in the details of your sub customer. If you are a reseller, the “billing_information” should point to your own invoicing details.

The “managing_account” must point to your own (reseller) account ID. In order to find your own account ID, please use the accounts_list operation.

The account that does not have a “managing_account” is your account.

After creation, a GET request will retrieve the status of the contract creation request. The “state” and “status” attributes give an indication of next steps. This could involve an out-of-band membership process, document signing, the creation of contacts/roles, or the order of a network service to activate a membership.

The “state” attribute is a single word indicating the state of the account, e.g. “requested”, “production”, “error” (see States Documentation. )

The “status” is a more detailed, human-readable description of the account state, including instructions on how to move from e.g. “requested” or “error” to “production”.

In order for an account to be operational or Terms & Conditions to be accepted, some exchanges may require contacts assigned to specific roles. The exchanges should provide such information in the account status field mentioned above.

You can create a contact with the contacts_create operation.

The role assignment can then be performed finding the requested role using roles_list.

Finally assigning the requested role to the created or pre-existing contact, with the role_assignments_create operation.

Some exchanges might support the provisioning of connections via IX-API, some will require you to order them using a different interface and process. For the first case, please refer to ordering a connection section . Regardless, any new network service will require a connection to be deployed onto, and therefore this constitutes a prerequisite to the follow up documentation.

Your connection list can be retrieved with the connections_list operation.

IX-API v2 supports a variety of network services from standard peering to various private interconnection options. In order to discover them you can list the product offerings with product_offerings_list.

Once found the suitable offering, its ID can be used to order the service itself. As mentioned above, some exchanges may require specific services to be ordered first for new accounts to move to production status. In that case the related info will be available in the account “status” field.

We will provide a guide for each different service provisioning starting from peering.

As mentioned above, you will need to find the suitable public peering service product offering, which would include properties such as specific LAN instance and bandwidth. The list of product offerings can be obtained using the product_offerings_list operation with an applied filter: GET /product-offerings?type=exchange_lan

The complete list of required properties is specified in the response of the product product_offerings_read endpoint.

Next you will need to create a Network Service Config (NSC) which will represent your public peering service. In order to do that, you will require several properties as described in the network_service_configs_create operation.

We list here the steps to obtain all the required properties.

The type for the NSC must match the type of the network service which in this case is exchange_lan.

The product_offering ID is the same as the previously selected product offering response.

Likewise, the network_service ID is available in the previously selected product offering response under exchange_lan_network_service.

You will also need account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange.

Next you will need to specify on which connection the service will reside. On how to obtain a connection ID please refer to Connection.

The connection needs to be in the same handover_metro_area_network specified in the product offering.

When creating an NSC will also require a vlan config. Please see the Service VLAN section on how to specify it.

Specific services require specific contacts to be assigned to specific roles in that service context. Effectively being responsible for certain aspects of the service lifecycle (E.g: NOC contact supposedly reachable 24/7 for emergencies). You can find the required role assignments for a NSC in the corresponding network_services_read response in the nsc_required_contact_roles property.

Once you found out the required role assignment you need to either pick from existing or create the corresponding role assignments and specify their role assignments IDs during the creation of the NSC.

Finally, for public peering services, you will also require a MAC address. You can list mac addresses using macs_list or register a new mac address via macs_create.

Once you have selected a suitable MAC address you can use the MAC address ID during the creation of the NSC.

Some exchanges might require you to create a Network Feature Config (NFC) alongside the NSC.

You can find the required Network Features to configure for a specific NSC with the network_features_list operation and providing the ID of the network service and required as filters: GET /network-features?required=true&network_service=<network_service_id>

If an NFC is required the corresponding NSC will stay in an error state until the NFC has been created. On how to create a NFC please refer to setting up a Route Server Session .

Depending on each exchange level of automation the provisioning of the service may or may not be on demand. Because of that you may need to poll the state of the newly created service via this using network_service_configs_read

You may want to update the peering IP FQDN, in order to do so you will need to find the IP address the exchange assigned for your public peering service, using the ips_list operation, filtering by network service config ID: GET /ips?network_service_config=<nsc_id>

And then you will need to update the FQDN property with ips_partial_update .

First you will need to choose the right MAPS Product Offering which includes properties such as specific LAN instance and bandwidth. Use the filters to find a product offering that matches.

The resource_type of the product offering should be network_service_config.

You now will need to find the MAPS network service to configure by querying the Network Services endpoint and filter by the ID of the product offering using network_services_list: GET /network-services?product_offering=<id>

Next you will need to create a Network Service Config (NSC) in order to join the MAPS virtual circuit. You will require several properties as specified in the network_service_configs_create operation.

We list here the steps to obtain all the required properties and constraints.

• The type for the NSC must match the type of the Network Service.
• The product_offering ID is the same as the previously selected Product Offering response.
• The network_service ID is retrieved from the network_service_list query.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange.

Next you will need to specify on which connection the service will reside. On how to obtain a connection ID please refer to Connection in Getting Started. The connection needs to be in the same handover_metro_area_network specified in the product offering.

When creating an NSC will also require a vlan config. Please see the Service VLAN section on how to specify it.

This service may require specific contacts to be assigned to specific roles in that service context. You can find the required role assignments for a NSC in the nsc_required_contact_roles property in the Network Service you queried before.

After creating the Network Service Config, you need to set up a Route Server Session.

Query the network_services_list endpoint to retrieve the list of Network Services. You can filter by type in order to only list closed user groups: GET /network-services?type=mp2mp_vc

Within the result set, choose the appropriate network service. Normally, the closed used groups identify themselves via the property display_name.

The selected Network Service contains the property nsc_product_offerings which is a list of compatible Product Offerings of resource_type: network_service_config. You can use those ids to filter the product_offerings_list endpoint: GET /product-offerings?id=id1,id2,id3...

Once, you found a suitable product_offering (i.e. by choosing bandwidth or handover_metro_area_network) you can go ahead and create the Network Service Config. For this, use network_service_configs_create with the network_service and selected product_offering IDs.

Some exchanges require or allow mp2mp_vc circuits with MAC ACL Protection. In those cases, you would find a value describing the policy in the Network Service object in property mac_acl_protection.

For the selection and adding a MAC Address, please see configuring Exchange LAN Public Peering.

We list here the steps to obtain all the required properties.

• The type for the NSC must match the type of the network service which in this case is mp2mp_vc.
• The product_offering ID from the previously selected product offering response.
• The network_service ID selected earlier.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange.

Next you will need to specify on which connection the service will reside. On how to obtain a connection ID please refer to Connection . The connection needs to be in the same handover_metro_area_network specified in the product offering.

When creating an NSC will also require a vlan config. Please see the Service VLAN section on how to specify it.

Specific services require specific contacts to be assigned to specific roles in that service context. Effectively being responsible for certain aspects of the service lifecycle (E.g: NOC contact supposedly reachable 24/7 for emergencies). You can find the required role assignments for a NSC using network_services_read on the selected Network Service in the nsc_required_contact_roles property.

Once you found out the required role assignment you need to either pick from existing or create the corresponding role assignments and specify their role assignments IDs during the creation of the NSC.

First select a product offering of the type mp2mp_vc matching your criteria like handover and service metro area network.

Then create the network service using network_services_create with type mp2mp_vc and providing the ID of the selected product_offering.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange. Optionally you could specify a display name for the network service to make it easily identifiable by other users.

Closed user groups can have an either public or private joining policy.

If private, the network service is only visible to users that have been invited by the owner by creation of a specific member joining rule for the joining member.

If public, the network service is visible to all users of the API and able to join unless there is a member joining rule in place, denying such access.

Creat a member joining rules with the member_joining_rules_create operation.

You can choose to either allow or deny access to a customer identified by the consuming_account property. You need to specify the id of the network_service.

In case of allow, you can specify a minimal bandwidth requirement or limit.

Some exchanges might require you to join your own mp2mp_vc Network Service in order for it to become operational. In this case, follow the instructions in the above section.

First select a product offering of the type p2p_vc matching your criteria like handover and service metro area network.

Then create the Network Service using with the network_services_create operation.

Choosing the type: p2p_vc and providing the id of the selected product offering.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange.

Furthermore private virtual circuits require you to specify a joining_member_account. That is the account ID of the B side party of the service. The account ID for the B side has to be communicated directly by the user, alternatively if the B side user specified in account property discoverable as true such ID would be queryable using accounts_list.

Finally if you want to create a private virtual circuit between two of your own connections you can specify your own account ID as joining_member_account.

Optionally you could specify a display_name for the network service to make it easily identifiable by other users.

Once the Network Service is created then you can proceed creating the respective A-Side Network Service Config.

The created Network Service has the property nsc_product_offerings which is a list of compatible resource_type Network Service Config Product Offerings. If the property contains an empty list that means that the NSC does not have a commercial impact and can be created without the product offering property. If not empty, you can use those ids to filter the product_offerings_list endpoint like this GET /product-offerings?id=id1,id2,id3...

Once, you found a suitable product_offering (i.e. by choosing bandwidth or handover metro area network) you can go ahead and create the Network Service Config. For this, use network_service_configs_create with the network_service id and product_offering which can be found here.

We list here the steps to obtain all the required properties.

• The type for the NSC must match the type of the network service which in this case is p2p_vc.
• The product_offering ID from the previously selected product offering response.
• The network_service ID selected earlier.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange.

Next you will need to specify on which connection the service will reside. On how to obtain a connection ID please refer to Connection . The connection needs to be in the same handover_metro_area_network specified in the product offering.

When creating an NSC will also require a vlan config. Please see the Service VLAN section on how to specify it.

Specific services require specific contacts to be assigned to specific roles in that service context. Effectively being responsible for certain aspects of the service lifecycle (E.g: NOC contact supposedly reachable 24/7 for emergencies). You can find the required role assignments for a NSC using the network_services_read operation under nsc_required_contact_roles.

Once you found out the required role assignment you need to either pick from existing or create the corresponding role assignments and specify their role assignments IDs during the creation of the NSC.

In order to configure the B-Side you will need to know the Network Service ID for the private virtual circuit.

Unless you received the ID directly from the inviting party, you can use the network_services_list operation to retrieve the list of already existing network services and filter by type=p2p_vc in order to only list Private Virtual Circuits. Within the result set, choose the appropriate object. Normally, the private virtual circuits identify themselves via the property display_name.

Once the network service has been identified the B-Side Network Service Config can be created following the same instruction as the A-Side, as specified in the above section.

Both NSCs need to be compatible with the NS specifications and only when the three entities’ creation has been performed can they be provisioned.

This workflow assumes that relevant product parameters are configured within the cloud service provider before the IX-API is consulted. E.g: for Azure, you would first create a service key in the Azure portal or Azure API which implies a bandwidth and service location.

After this service has been created, you would need to select a compatible product offering from the product offerings endpoint. A compatible product offering has the same product parameters as the ones specified with the cloud provider system.

Some exchanges provide filtering by cloud_key. Using this filter, the product_offerings_list endpoint returns compatible product offerings for those implied product parameters: GET /product-offerings?cloud_key=<azure_service_key>

The Product Offering object contains further information about the services which can be consumed within the cloud providers network. For example, the provider_vlans property explains if the circuit combines multiple VLANs behind it. (see Azure Express Route Peerings)

In this case, the cloud_vlan property used in the network_service_configs_create operation contains information about the on-ramp side (the exchange connection to the cloud provider). For example, a null value would group all existing peerings and transport them over the circuit unchanged while a specific value (referring to a specific peering) would strip those tags before it transmits them over the circuit.

The diversity property of the product offering object refers to the amount of on-ramp connections, i.e. a value of 1 means there is no built-in redundancy when creating a network services from this product offering, while a value of 2 means there are two paths from the exchange network to the cloud service provider. In the case of Microsoft Azure, the diversity value is always 2 which means you would have to either select the primary or the secondary path in the NSC creation.

The path to the cloud provider is selected by providing the handover property when creating the network service using network_services_create.

You need to select from those product offerings and then use the cloud_key in the request to create the network service.

After that, you need to go ahead and create actual point to point configurations by creating network service configs of type cloud_vc which point to that network service using the network_service_configs_create operation. Exchanges may accept unique combinations of the handover and cloud_vlan value pairs creating a total of diversity times possible cloud_vlan value combinations.

We list here the steps to obtain all the required properties.

• The type for the NSC must match the type of the network service which in this case is cloud_vc.
• The product_offering ID from the previously selected product offering response.
• The network_service created earlier.

You will also need Account IDs (managing_account, consuming_account, billing_account). If you are creating the service for yourself they will all match. Otherwise the consuming_account will be your sub-customer account ID and the billing_account could either be your or your sub-customer account ID depending on the billing policy of the exchange.

Next you will need to specify on which connection the service will reside. On how to obtain a connection ID please refer to Connection . The connection needs to be in the same handover_metro_area_network specified in the product offering.

When creating an NSC will also require a vlan config. Please see the Service VLAN section on how to specify it.

Specific services require specific contacts to be assigned to specific roles in that service context. Effectively being responsible for certain aspects of the service lifecycle (E.g: NOC contact supposedly reachable 24/7 for emergencies). You can find the required role assignments for a NSC using network_services_read on the selected Network Service in the nsc_required_contact_roles property.

Once you found out the required role assignment you need to either pick from existing or create the corresponding role assignments and specify their role assignments IDs during the creation of the NSC.

Network features are additional functionalities to network services. Currently, there is only a single type of network features, which is route_server. Those route server network features only make sense in the context of peering (i.e. Public Peering or MAPS ).

You can find all existing network features with the network_features_list operation.

Network features have flags which represent configuration options. For example, an exchange may choose to enable the client to configure RPKI filtering on the BGP session. In this case, the network feature returns a flag called RPKI with an appropriate description. Some of those flags are always enabled. As such, their mandatory property is set to true which means they may never be disabled. The purpose of those mandatory flags is purely for documentation.

Network features describe route server instances while network feature configs describe sessions on those instances. In order to create a route-server session, you would first need to have a fully provisioned network service config which means it is in state production (or in an error state if the NFC is required for that NSC). It is safe to assume that this network service config contains ip addresses that can be used in the peering context and that corresponding network service refers to a list of network features. You can create the NFC with network_feature_configs_create.

There can be one BGP session between each pair of NSC IP addresses and network features. You have to choose the IP address from the list of IPs of the NSC and specify it as part of the NFC creation.

Network services as well as network service configs can be terminated. While those objects are often bound to service contracts, they may have certain cancellation policies. There is a dedicated endpoint for network services as well as network service configs which can be queried to answer the questions:

1. When can the service technically be decommissioned
2. When does my obligation to pay for it ends

For network service configs you can retrieve the cancellation policy using the network_service_config_cancellation_policy_read and for network services the network_service_cancellation_policy_read operation.

You may provide a request parameter for the earliest decommissioning date: GET /network-service-configs/<id>/cancellation-policy?decommission_at=YYYY-MM-DD. The response then contains a decommission_at property which can be passed in the request body to the deletion of network services and network service configs.

To request the cancellation, use network_services_destroy for Network Services and for Network Service Configs use network_service_configs_destroy

If you omit the decommission_at request parameter, the earliest possible date will be assumed.

For all Network Service Configs associated with a Network Service which is about to be decommissioned, the deletion cascades.

Furthermore, the deletion of Network Service Configs cascades to Network Feature Configs and Member Joining Rules.