Overview
This API provides the ability to create and retrieve quotes for BT Wholesale Ethernet and Wholesale Optical products. The REST API is based on the standards set by the TM Forum Quote Management API (TMF648). More information about the specification can be found on the TM Forum website. This API provides similar functionality to the BT Wholesale SOAP based API (version 6).
The API provides quoting for the following products:
- Wholesale Ethernet E-Line
- Wholesale Ethernet E-Lan
- Wholesale Ethernet Internet
- Wholesale Optical
The Quote Management API is synchronous and quote pricing is returned in the response. There is no need to provide call back URLS for notifications. Quotes are saved for 1 month and can be retrieved using the GET method operations.
Quote structure
Unlike the SOAP API that provides a dedicated quote operation per product the REST API uses a single REST POST method for all products. Refer to the API specification reference documentation for individual quote product examples and the schema definition.
Products must be individually quoted; this means that it is not valid to have a quote with a mixture of different products. For instance, a Wholesale Ethernet E-Line quote cannot also include a Wholesale Optical product.
A single quote may contain up to 100 quote items, where each quote item would usually be associated with a place and a product service. Depending on the product the quote item may have multiple product services, for example an Etherway and an Etherflow service.
The quote structures vary by product and can best be visualised by exploring the API specification reference documentation. At a high level the different product quote structures are:
Wholesale Optical – each quote item contains two places e.g. the A-End and the B-End and one product service e.g. Wholesale Optical Service 1 x 10Gbit/s.
Wholesale Ethernet E-Lan and Wholesale Ethernet Internet – they share the same structure where each quote item has a single place e.g. the B-End and two product services, an Etherway and either an Etherflow Dynamic or Etherflow Internet.
Wholesale Ethernet E-Line – this structure is a bit more complicated to account for either point to point networks or hub and spoke network scenarios. There is an example of both network types in the specification examples.
Product Information
Product overviews have been provided below to provide high level understanding in relation to quoting the products in the Quote Management API. For more detailed product information, found in the relevant Product Handbook, please go to BTWholesale.com or contact your BT Wholesale Account Manager.
BT Wholesale Ethernet (Etherflow Connected (E-Line) & Etherflow Dynamic (E-LAN))
BTWE is a component-based product consisting of a physical access (Etherway Access) and virtual paths (EVCs – Ethernet Virtual Connections) known as Etherflow Connected (E-Line) or Etherflow Dynamic (E-LAN), between two Ethernet ports in a point-to-point, point-to-multipoint, meshed or any to any configuration. It enables customers to connect sites into the BT 21C core network using Etherway Access and link those sites throughout the UK via virtual circuits (Etherflow).
- Etherway is offered at access bandwidths of between 1Mbit/s and 10Gbit/s.
- Etherflow (EVC) bandwidths range from 0.2Mbit/s through to 10Gbit/s.
A point-to-point Wholesale Ethernet service consists of two Etherway Accesses and one Etherflow between BT nodes, with each component is allocated a unique Service Reference.
Additional Etherway Access is available via a growing number of Data Centre locations using our Bespoke Access functionality. Etherway Data Centre Connect provides 1Gbit/s and 10Gbit/s (subject to availability) fibre hand off via a patch panel from a BT switch co-located in the Data Centre.
For Etherflows we offer both E-LAN (Etherflow Dynamic) and E-LINE (Etherflow Connected). E-LAN offers full any-to-any connectivity capability along with improved CoS offerings. Its full name is BT Wholesale Ethernet E-LAN and it uses the same 21C network as the established E-Line based service (Wholesale Ethernet).
Access Types for BTWE include:
- Etherway Fibre (EAD, OSA)
- Etherway Superfast GEA (FTTC, SOGEA & FTTP)
- Etherway Radio
- Etherway Exchange Connect (EEC)
- Etherway Data Centre Connect (DCC)
- Etherway Hull Access
Wholesale Ethernet Internet - Wholesale Ethernet Internet supports the delivery of Etherflow Internet connection with an Etherway Fibre as part of a new product bundle. Direct Internet Access supports an Etherway Fibre access with bandwidths of between 100Mbit/s up to 10Gbit/s. The service enables customers to connect the end user/ customers sites into the BT 21C core network using an Etherway Access and link those sites through directly to the internet as a layer 3 connection. The Etherflow Internet (EVC) bandwidths range from 30Mbit/s through to 10Gbit/s. (Where network service allows) NOTE: the point-to-point service Wholesale Ethernet Direct Internet Access service consists of one Etherway Access (retaining the ETHA reference) and one Internet peering Etherflow between the BT node and the Etherway, (this will have a unique Service Reference of ETHI).
Wholesale Optical. Wholesale Optical delivers high bandwidth symmetric, point to point connectivity between customer equipment installed at BT exchanges, customer’s own premises and/ or third party locations including data centres and UK cable landing stations. The price paid by a customer will be determined by four components:
- The Openreach access product (if applicable)
- The distance from the customer’s equipment to the Ciena 6500 DWDM multiplexer in the 21CN core/Metro Node
- The bandwidth requested by the customer
- The distance between the Core Nodes and/or Data Centre Nodes
Wholesale Optical does not offer a “sub-rate” service. A customer cannot request less than 10Gbs of bandwidth on a 10GE service, or less than 100Gbs of bandwidth on a 100GE service.
Valid Services and Sites
The table below outlines the different types of sites that are valid for each type of the Wholesale Ethernet Etherway service. For instance, a postcode can be used to quote all Etherway services, however a directory number can only be used for Etherway GEA.
| Different Site Types | Etherway Fibre | Etherway OSA | Etherway Exchange Connect | Etherway GEA | Etherway Data Centre | Etherway Radio |
| PostcodeSite | Yes | Yes | Yes | Yes | Yes | Yes |
| CoordinateSite | Yes | Yes | Yes | No | No | Yes |
| DirectoryNumberSite | No | No | No | Yes | No | No |
| NadKeySite | Yes | Yes | Yes | Yes | No | Yes |
| UPRNSite | Yes | Yes | Yes | No | No | Yes |
| DataCentreSite | Yes | No | No | No | Yes | No |
| ExchangeConnectSite | No | No | Yes | No | No | No |
| AccessLineIdSite | No | No | No | Yes | No | No |
Commercial and Pricing Information
It is important to note that all pricing and service availability information returned by the API is indicative and non-binding. Firm pricing is provided at the order stage of the product purchasing process. This is in line with pricing provided by the BT Wholesale pricing tool web application. In addition, pricing may not include other service-related charges, for instance excess construction charges.
Products may have different contract term options; for example, 1 year pricing, 3 year pricing and 5 year pricing. All available product term options will be returned in the quote response. Some products may have Option B pricing.
Option B is a 2nd pricing option for a term period so that a customer can choose between two pricing options, typically this is a choice between two connection prices (one low, one high) and a corresponding rental (one high, one low). An example is on 1G Etherways on 3 year term Option B where we give the option of a higher connection charge (rather than typically free) in return for a lower rental than the normal 3 year term.
Sandbox API
The sandbox API is a fully functional test environment. This means that responses are not stubbed however it is important to note that actual pricing will not be accurate. The purpose of the sandbox API is to provide a facility for onboarding, system integration and general functional testing. Pricing and service availability information must not be used from the sandbox API in production systems.
The API response includes a header ‘X-System-Environment’ that identifies if the API environment is sandbox or production.
API Testing and Integration
It may be helpful whilst integrating the API to make use of the web-based pricing tool. This will help provide an idea of how the products are structured and the types of inputs that combine to produce a quote.
Access to the web-based pricing tool can be requested from the BT Wholesale website. You will first need to create a BT Wholesale portal account; this can be requested from the BT Wholesale website. Once your account has been created and you have logged into the BT Wholesale website go to ‘My BT Wholesale’. Click on the menu option ‘App A-Z’ and select letter “B”. Scroll down and select ‘BT Wholesale Pricing Tool’ and click on the register for access button.
Once the request has been approved you will have access to the web-based pricing tool and be able to access it under ‘My apps’ in the ‘My BT Wholesale’ area of the website. Note it can take a couple of days for access to be provided by the portal team.
Rate Limiting and API use
The pricing tool API operates a fair use policy, as such API transactions are rate limited to ensure all customers get a good service. If an application that uses the pricing tool API regularly exceeds the API rate limit or uses a disproportionately larger number of requests, access may be revoked. The API response includes various rate limit headers that detail the rate limit set, how many requests are remaining in the current period and the reset time.
When calling the API do not send multiple concurrent transactions in parallel. The way the pricing tool is designed is that it caches expensive calls to downstream systems. For example, if the requirement is to price 10 types of access/bandwidth permutations for a given postcode, it is extremely inefficient to send 10 separate requests in parallel. In addition to the extra processing overhead, if the pricing tool needs to make downstream system calls it would result in 10 separate calls being made for the same postcode. This would increase resource utilisation and add additional delays getting back the relevant information. Some downstream systems also have strict usage policies and may disallow multiple requests, resulting in errors.
The same requirement can be met by sending a single request containing 10 circuits, each circuit using the required service/bandwidth permutation for the same postcode site. The pricing tool API will cache expensive calls to downstream systems so the postcode information would be cached after the first call and the subsequent 9 circuits would make use of the cached information and not make further calls to other systems.
Not implemented (reserved for future use)
New functionality is periodically added to the pricing tool as and when it becomes available in the business. Some of this functionality impacts the pricing tool API. To help minimise new API versions being released with every new feature we look ahead and try to future proof the API as much as possible. As such some of the options in the API schemas are not yet implemented in the pricing tool. These new features are reserved for future use and will be implemented when the functionality is introduced to the pricing tool.
Currently the following features are not yet implemented. As they are introduced into the pricing tool API they will be removed from the below table.
| Operation / Feature | Description |
|
Etherway Radio access |
Quoting Etherway Radio access is not yet launched. |
| Etherway GEA FoD service | Quoting Etherway GEA FoD (FTTP on demand) bandwidths is not yet launched. |
| Etherway GEA FTTP bandwidths | Quoting for some Etherway GEA FTTP bandwidths is not yet launched (see GEA bandwidth table below). |
GEA bandwidths
| Bandwidth | Status |
| SOGEA 0.5:0.5 Mbit/s | Not yet implemented |
| SOGEA 40:10 Mbit/s | Available |
| SOGEA 80:20 Mbit/s | Available |
| FTTC 40:10 Mbit/s | Available |
| FTTC 80:20 Mbit/s | Available |
| FTTP 0.5:0.5 Mbit/s | Available |
| FTTP 40:10 Mbit/s | Available |
| FTTP 80:20 Mbit/s | Available |
| FTTP 115:20 Mbit/s | Available |
| FTTP 160:30 Mbit/s | Available |
| FTTP 220:20 Mbit/s | Available |
| FTTP 220:30 Mbit/s | Available |
| FTTP 330:30 Mbit/s | Available |
| FTTP 330:50 Mbit/s | Available |
| FTTP 500:165 Mbit/s | Available |
| FTTP 500:500 Mbit/s | Not yet implemented |
| FTTP 550:550 Mbit/s | Not yet implemented |
| FTTP 550:75 Mbit/s | Available |
| FTTP 1000:115 Mbit/s | Available |
| FTTP 1000:220 Mbit/s | Available |
| FTTP 1000:1000 Mbit/s | Not yet implemented |
| FTTP 1100:1100 Mbit/s | Not yet implemented |
| FoD 500:500 Kbit/s * | Not yet implemented |
| FoD 115:20 Mbit/s | Not yet implemented |
| FoD 160:30 Mbit/s | Not yet implemented |
| FoD 220:20 Mbit/s | Not yet implemented |
| FoD 220:30 Mbit/s | Not yet implemented |
| FoD 330:30 Mbit/s | Not yet implemented |
| FoD 330:50 Mbit/s | Not yet implemented |
| FoD 500:165 Mbit/s | Not yet implemented |
| FoD 500:500 Mbit/s | Not yet implemented |
| FoD 550:550 Mbit/s | Not yet implemented |
| FoD 550:75 Mbit/s | Not yet implemented |
| FoD 1000:115 Mbit/s | Not yet implemented |
| FoD 1000:220 Mbit/s | Not yet implemented |
| FoD 1000:1000 Mbit/s | Not yet implemented |
| FoD 1100:1100 Mbit/s | Not yet implemented |
Support
If you are having trouble integrating the API into your application, it might be easier to try and send some example JSON requests using curl or Postman. If you encounter HTTP error responses, please refer to the API specification for more information about the error.
Example scenario diagrams
