Location: Vancouver, BC
Employees: 20,000 +
Telus is a Canadian national telecommunications company that provides a wide range of telecommunications products and services including internet access, voice, entertainment, healthcare, video, and IPTV television.
An aging platform that wasn’t scaling
Any API program more than a decade old must deal with multiple services in different stages of the lifecycle. As part of evolving your technology, you can expect to move on from once-standard choices like SOAP. One of Canada’s biggest telecommunication companies, Telus, knows times have changed, and the company is transforming its software workflow with the help of Stoplight.
Telus needed a modernized approach to its API design and governance. It wanted to improve upon an aging platform that mainly supported SOAP APIs and consolidate REST API documentation and guides. The company assembled a team to evolve their process, which now governs their path from API conception to production.
In the rest of this post, we’ll look at how Telus based its program on four pillars, its “front door” approach to help teams create reusable APIs, and how Stoplight has supported more than 1,000 Telus team members to build better APIs.
Rethink Enterprise Architecture to transform the business
Telus offers its customers a wide range of services, from internet access and voice to television and even digital healthcare. Many of these initiatives were driven by legacy service-oriented architecture (SOA), with primarily XML-based APIs that needed updates. Because they were built with many different approaches, there were inconsistent API designs and non-centralized documentation.
The SOA platform was difficult to update after 12 years of usage. Because it was tightly integrated, the team could not pull individual pieces apart. As can happen, the legacy system became a barrier to moving quickly. Telus attempted to keep up with its complex upgrades, but they still struggled to streamline documentation and support REST services. Teams provided API documentation in an irregular mixture of Word, JSON, and YAML files that were difficult to organize.
The experience highlighted the legacy platform’s inflexibility and brittle design, driving them to re-evaluate how they work with APIs. Considering Telus employs tens of thousands of people, a new solution would have a big impact.
Telus set out to rework its Enterprise Architecture and modernize existing workflows, with the goal of delivering microservices in a quick and streamlined fashion. The group defined a next-generation API program that identified critical aspects of building APIs, which became its Four Pillars:
These pillars set the foundation of development patterns, tooling and automated processes necessary to push their API program forward. With these pillars in mind, the group began revising how Telus works with APIs to solve its legacy platform limitations. We’ll learn about the API program’s new workflow in the following section.
Bring consistency and automation to their workflows
Building upon the pillars, Telus needed to guide teams to create APIs using a new process, with an aim to bring consistency and automation to their workflow. With a combination of guidelines and review, architects can collaborate with development teams to meet a set of requirements. It all starts with a front door process from a team with an API concept. That team creates a ticket, which initiates dialog with one or more Telus enterprise integration architects.
Front Door API Process:
Along with manual reviews, Telus created an internal “starter doc” to help teams create their first API using the new process. In addition, Telus helps teams adhere to style guides using Stoplight’s editor and built-in linter. Machine-readable best practices and automatic linting allow for faster review and a better chance of getting it right the first time.
The in-depth reviews, both manual and automated, ensure any new API is not redundant to existing services and will be consistent with their expectations of modern Telus APIs.
Telus now has many development teams jumping into the newly outlined workflow for API development. With the front door process extending collaboration, Telus users are actively participating in designing and developing APIs.
Telus highlights two features in particular that help them move quickly within Stoplight: lifecycle tagging and automated linting rules.
After an API request is approved, an API architect guides the requesting team into a Stoplight project for the new API. Telus then coordinates the API development tasks and contributors by applying Stoplight lifecycle tags to the project. These tags govern the workflow, automate tasks, and support Telus’ interdepartmental communication.
These tags can kick off initial review, onboarding the API to the gateway, or even taking the new API to production. Telus effectively collaborates at every stage of the API development and can clearly see which APIs are at what stage. Even before a human reviews a new API, Stoplight helps Telus teams stay consistent. With customized linting rulesets, API style decisions are checked after every update to an API design, enabled by built-in support for Stoplight’s open source tool Spectral.
For example, each Telus API design must reference its “front door ID” so reviewing teams can connect the API description to the architect’s guidance notes. Similarly, there are basic items that Telus expects of every API, such as including one of a small number of whitelisted servers. The linting rulesets allow the checks to happen automatically and proactively, saving both the development and review teams unnecessary back-and-forth.
With a combination of human-readable API designs via OpenAPI/Swagger and linting rules, Telus guides their teams to create better APIs. As they evolve the linting rulesets, Telus wants to enable support for other best practices, such as TMF630 API design guidelines, ensuring API quality at an industry-leading level.
As API programs evolve, flexible tools and standards allow companies like Telus to efficiently create more consistent APIs. From harnessing the right level of internal collaboration to embracing automation, the Telus journey moved it beyond its painful legacy SOAP API platform. The architecture team created and then built upon four pillars, initiating a front door method to streamline how it designs and builds APIs.
Bring consistency and speed to your API workflow by standardizing guidlines using Stoplight within your team.