Getting Started

Account

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”.

POST /accounts accounts_create
{
  "managing_account": "<my_account_id>",
  "name": "Moonpeer Inc.",
  "legal_name": "Moon Network Services LLS.",
  "external_ref": "IX:Service:23042",
  "discoverable": false,
  "metro_area_network_presence": [
    "14021",
    "12939"
  ],
  "address": {
    "country": "US",
    "locality": "Mountain View",
    "region": "CA",
    "postal_code": "9409",
    "street_address": "1600 Amphitheatre Pkwy.",
    "post_office_box_number": "2335232"
  }
}
Status: 201 Content-Type: application/json Response
{
  "state": "requested",
  "status": [
    {
      "severity": 2,
      "tag": "toc_required",
      "message": "It is required to upload the signed Terms of Conditions document.",
      "attrs": {
        "url": "https://documents.my-ix.example/"
      },
      "timestamp": "2019-08-24T14:15:22Z"
    }
  ],
  "managing_account": "my-account",
  "name": "Moonpeer Inc.",
  "legal_name": "Moon Network Services LLS.",
  "external_ref": "IX:Service:23042",
  "discoverable": false,
  "metro_area_network_presence": [
    "14021",
    "12939"
  ],
  "id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "address": {
    "country": "US",
    "locality": "Mountain View",
    "region": "CA",
    "postal_code": "9409",
    "street_address": "1600 Amphitheatre Pkwy.",
    "post_office_box_number": "2335232"
  }
}

Contact

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.

POST /contacts contacts_create
{
  "managing_account": "<my_account_id>",
  "consuming_account": "<customer_accont_id>",
  "name": "Some A. Name",
  "telephone": "+123 123123123123",
  "email": "info@moon-peer.net"
}
GET /roles roles_list
Status: 200 Content-Type: application/json Response
[
  {
    "id": "role:noc",
    "name": "noc",
    "required_fields": ["name", "email"]
  }
]
POST /role-assignments role_assignments_create
{
  "role": "<role_id>",
  "contact": "<contact_id>"
}

Connection

Some exchanges might support the provisioning of connections via IX-API, some will require you to order them using a different interface and process. In the first case, you order one with the connections_create operation. 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.

GET /connections connections_list
Status: 200 Content-Type: application/json Response
[
  {
    "state": "production",
    "status": [],
    "current_billing_start_date": "2019-08-24",
    "managing_account": "<my_account_id>",
    "consuming_account": "<my_account_id>",
    "billing_account": "<my_account_id>",
    "external_ref": "IX:Service:23042",
    "purchase_order": "Project: DC Moon",
    "contract_ref": "contract:31824",
    "role_assignments": [
      "c-impl:123",
      "c-noc:331"
    ],
    "mode": "lag_lacp",
    "lacp_timeout": "slow",
    "product_offering": "string",
    "id": "string",
    "name": "string",
    "ports": ["23", "42", "5"],
    "port_reservations": ["2312"],
    "pop": "pop:127388:LD3",
    "speed": 20000,
    "capacity_allocated": 0,
    "capacity_allocation_limit": 25000,
    "vlan_types": ["port", "qinq", "dot1q"],
    "outer_vlan_ethertypes": ["0x8100"],
    "port_quantity": 1,
    "subscriber_side_demarcs": []
  }
]

Service VLAN

Each creation of a Network Service Config requires a VLAN config to be specified.

The VLAN types and ethertypes offered by an Exchange can be discovered from the “vlan_types” and “outer_vlan_ethertypes” properties for each individual Connection. These may vary within an Exchange depending on constraints within connected hardware.

Exchanges may choose to support multiple types of VLAN tagging. Currently the possible types are:

  1. Dot1Q: Providing a single VLAN tag to identify the service.
  2. QinQ: Providing two VLAN tags to identify the service.
  3. Port: Untagged.

The supported ethertype of the outer tag in hexadecimal notation are: “0x8100” (standard 802.1q), “0x88a8” (802.1ad stacked tags), and “0x9100” (pre-802.1q Cisco VLAN tags)

Product Offerings

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.

GET /product-offerings product_offerings_list
Status: 200 Content-Type: application/json Response
[
  {
    "type": "exchange_lan",
    "id": "string",
    "name": "string",
    "display_name": "string",
    "exchange_logo": "https://example.ix/resources/ixpLogo",
    "service_provider_logo": "https://example.ix/resources/providerLogo",
    "product_logo": "https://example.ix/resources/products/activeCloudPremium",
    "resource_type": "network_service",
    "handover_metro_area_network": "191239810",
    "handover_metro_area": "met:29381993:NYC",
    "physical_port_speed": 0,
    "service_provider": "Example IX",
    "downgrade_allowed": true,
    "upgrade_allowed": true,
    "orderable_not_before": "2019-08-24T14:15:22Z",
    "orderable_not_after": "2019-08-24T14:15:22Z",
    "contract_terms": "2 weeks and 1 day, renewing every 37 days afterwards, first 66 days free",
    "notice_period": "at least 2 weeks before the end of every odd month",
    "provider_vlans": "single",
    "service_metro_area_network": "9123843",
    "service_metro_area": "met:213913485:LON",
    "bandwidth_min": 0,
    "bandwidth_max": 0,
    "exchange_lan_network_service": "network-service:123123"
  }
]