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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.