Stoplight Case Study

Promoting Reuse and the Design-First Approach: API Success with SPS Commerce

SPS Commerce maximized a design-first approach and Stoplight Platform to improve internal developer experience. Their design review process went from being a weeks-long effort to an hour-long effort by creating an effective design review process over multiple iterations. They combatted API sprawl, legacy code-first approaches, and company-wide buy-in on their API-first strategy.

The Goal: Improved Developer Experience

The SPS Commerce team is focused on building an API-based platform for their core capabilities. It requires a sophisticated API development lifecycle for developers and leveraging the API Design First approach to increase efficiency and streamline developer productivity and adoption.

However, the first step in their API innovation journey was getting their internal API management optimized and built into an API platform.

We spoke with SPS Commerce's Distinguished Software Engineer & Developer Experience lead, Travis Gosselin, to better understand their challenges and how Stoplight helped solve some of them.

"90% of our people use APIs, whether internal or external, but the internal number has increased a lot, so for us thinking about the developer experience internally and how all of our teams effectively build and consume APIs is important."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

Challenge One: API Sprawl

"There will always be people building APIs outside of your core team. It's not just the engineers; there are people in other parts of the organization that you'd never imagine building internal APIs. Getting a handle on API sprawl is part of tackling that internal developer experience challenge."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

To tackle API sprawl head-on and avoid siloed development, Travis and team introduced tooling and methodology that enables easy and efficient collaboration with teams during API design and delivery. This allows teams to test their ideas and design before they are heavily invested in development and writing code which is benefiting the entire organization. Essentially, they are working on transitioning out of a code-first approach and more into a design-first/API-first methodology.

The true benefits of an API-first and design-first language enforcement in the end will create a better developer experience. With many existing APIs and old cultural habits of building API with code-first approach, it presented a challenge in adopting API-First methods.

Challenge Two: Lack of Reusability

One of those challenges was that those teams were missing out on reusability of components, which would reduce work later on. However, by using a design tool like Stoplight that includes models and components that could easily be reused, that would solve that problem. Having a reusability factor to their components helps drive consistency and efficiency of API delivery which in turn produces greater business value at a quicker rate to their customers.

Challenge Three: Complicated Feedback Loops

The code-first approach also meant they were leaving their APIs and corresponding documentation not as initially accessible for certain stakeholders like technical product owners. With this approach, technical product owners can only provide feedback after the code is written, making the feedback loop more lengthy than if they were able to provide feedback during the design phase.

"I think that many people expect to have that impact right away with design-first. You get to be three, six months into it, and you're not seeing gains, but it takes a long time to get there because you have a lot of life cycle to put into place. There are several moving pieces needed in an organization for it to truly become a part of the API design lifecycle and see the results. But that being said, I think that along that journey, you can find incremental value."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

An agile organization, like SPS Commerce, allows for opportunities to add incremental value along the journey towards full adoption through iteration. Small additions and wins to modifying the API lifecycle enable them to make course corrections as they see what works for their team and what doesn't work in real time.

What does implementation and the design review process look like?

To tackle the move to a platform-focused approach, the SPS team needed to pivot the organizational structure, focusing on domain-driven design concepts to ensure service teams had clearly defined ownership of resources on the API platform for all the capabilities. Each department has a different domain technical lead driving design and implementation.

"Each of those domain leads are responsible for putting together an OpenAPI specification, and then they're responsible for starting to circulate that as a design asset as a part of an API design review with a much larger cross-functional group, who then looks at the design and thinks about it in comparison to the rest."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

Creating Taxonomies

The key part of that strategy is what the SPS team refers to as an 'API taxonomy', a system that identifies what APIs they have available today, where they're heading, and how the domains interact.

What that looks like in practice is taking the domain leaders and conducting a discussion to establish how their API(s) fits into the overall architecture of the platform. They ask questions such as: if that API addition is long-term, internal only, eventually a full public API, and more, to help regulate what kind of APIs they want to put out there.

Standardization and Regulation

Speaking of regulation, the SPS team also uses linting to enforce consistency of their standards and to reuse their shared domain entities. With the assistance of Stoplight's open-source linting tool, Spectral, the SPS team sees a substantial benefit in regulating the consistency between API endpoints across the platform.

"In Spectral, we built a great markdown guide but also paired it with the Spectral automation so that teams are getting both local designs as they're working away. That automation also includes other things we've added, such as API breaking change detection where we can compare the specs before they deploy out to production and see if there is actually an incompatible API change."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

Shared Design Platform for Design Reviews

Additionally, a shared design platform - which for SPS is Stoplight Platform - enables the technical team along with a variety of other stakeholders to collaborate. Each design review can look a little different, depending on the maturity of the API and the teams developing it, but it’s the API-first and the design-first approach that creates a focal point.

Travis stresses that thinking of that API as a product, especially to other stakeholders outside your core team, helps translate meaning properly.

"These review discussions are a pivotal practice for us to help engage teams to, in some cases, reach out and say, 'this API design doesn’t quite work. In fact, we think you didn't even look at the design standards. So let's get together and go through some of the ideas that you have to get you where you need to go."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

The SPS Commerce API team has been through this process many times, so they've established a quality schedule and set of standards that each API must meet. After someone has met the first step of having an OpenAPI spec, they can start evaluating it.

In some cases, they might just asynchronously ask them to go back and fix it, or they'll walk through it together. After, they take that API design to a group meeting with the rest of the relevant stakeholders where all can talk and take notes while editing the API spec in real time to understand what they're looking at visually.

"In these group design reviews, we're actually modifying the spec, seeing the preview output, and evolving it. Having a combination of the right technology and in-person discussion takes what used to take weeks and weeks before and now can be done in an hour or less."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

Tool Evaluation: Why Stoplight?

"One important thing we learned earlier on in our evaluation of different tools is that in this industry, there really is no one tool that solves it all. So, we have a mismatch of our paid tools (like Stoplight), as well as custom-created tool sets and some open-source tools as well."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

The team's current published portal and API catalog are all built through Stoplight. "Stoplight has a nice, searchable interface. It provides us solid discoverability, while searching across hundreds of our API projects," shares Travis.

But the number one thing that drove SPS Commerce to Stoplight was that Stoplight combines markdown with the Open API spec, which allows the team to create some 'higher quality documentation where we want it to be.'

The team's internal pivot from a code-first strategy to a design-first/API-first approach influenced the decision to go with Stoplight. Company-wide, SPS adopted an API-first mentality as a part of a full organizational shift. This allowed teams to align their API's with our API Taxonomy and domain, enabled collaboration and early feedback.

From there, the team really started driving home the design-first approach in all that they do to ensure the right stakeholders had a seat at the table from the get-go. This allowed the team to
focus on the idea of technical product owners genuinely being a part of and owning the API as a product process. Now, that doesn't mean they were able to convince all teams to forgo code-first entirely, and they do still offer it as long as the approach ends up with the same results and outputs.

"To be fair, we see a lot of those teams still trying to do code-first, eventually saying, 'Maybe I don't want to do code first. There's all these other additions and headaches.' So I think as a company we'll all get on the design-first train eventually, and that shift is definitely happening."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

Another way Stoplight helped improve developer experience is through reuse and repurpose of different API components. The SPS team often has multiple teams developing domain schemas, and having easily replicable and reusable schemas like the Component Libraries feature in Stoplight, saves, in Travis’ words “a ton” of time.

"For us, it may not be a component that I want to include everywhere. Like, I just need this object reference, or I need to comply with this one certain requirement that's difficult to include without customization inside your code. But being able to say, 'Oh, because we already have this reusable component, I can do a one-line include, and now it's my error scheme automatically."

– Travis Gosselin, Software Engineer & Developer Experience Lead, SPS Commerce

What's next for SPS Commerce?

Overall, as the developer experience improves, Travis states that the team's next goal is enabling further automation across the API Lifecycle and extending their own internal API success towards the future SPS Commerce Network API. For more on the SPS story and their workflow process, check out their podcast episode from API Intersection.

Create consistency and enable collaboration at your organization. Include Stoplight to help your team go API design-first.

Create a free Stoplight workspace

Industry: Retail

Location: Minneapolis, MN

Employees: 2,509

SPS Commerce connects retail trading partners together and empowers data collaboration in the retail supply chain with industry-leading technology. They are the world's largest retail network, servicing more than 115,000 retail supply chain partners around the globe.

Ready to streamline API design and development?