Telus

🔗 🔗 🔗 🔗 🔗 🔗 🔗 Customer Overview

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.

Use Case
API Governance
Solution
Linting, Visual Design and Lifecycle Management
Tools
Spectral and Stoplight Platform

🔗 🔗 🔗 🔗 🔗 🔗 🔗 CHALLENGE

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.

🔗 🔗 🔗 🔗 🔗 🔗 🔗 OBJECTIVE

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:

• Architecture and Governance: ensure consistency within the API program by creating company wide standards and patterns.
• Tools and Enablement: provide the right tooling across the API lifecycle to help teams create new APIs efficiently.
• Design and Development: create design, development and delievery processes to ensure API delivery with consistency and speed.
• Communication: streamline how teams coordinate and communicate about APIs. This included stakeholder management, and internal/external communications.

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.

🔗 🔗 🔗 🔗 🔗 🔗 🔗 SOLUTION

Bring consistency and automation to their workflows

🔗 🔗 🔗 🔗 🔗 🔗 🔗 Systematic Front Door Method Increases Reusability

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:

1. API concept request, review, and assessment with an enterprise integration architect
2. API design developed in a Stoplight project by the development team
3. Stoplight project submission, review, and approval
4. Onboard new API to the gateway with Stoplight API automations

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.

🔗 🔗 🔗 🔗 🔗 🔗 🔗 How Stoplight Empowers Telus APIs Across the API Lifecycle

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.