Delivering on Documentation and Developer Experience - Sendcloud's Story
API development at Sendcloud involves the participation of a cross-functional team of hundreds of different stakeholders. To be successful, they must collaborate in an organized way, follow shared standards, and achieve common business goals—the hallmarks of a design-first strategy.
"My favorite thing is the Stoplight Studio. It's a very powerful tool, which allows you to work and iterate very fast. It helps the product and business sides to understand what you're building," – Kostas Petrakis.
Sendcloud is Europe's top shipping automation platform focused on making the e-commerce journey from order to shipment as easy as possible. They have been API-driven since the beginning, and their move to a design-first mentality has dramatically positively impacted achieving their goals.
API development at Sendcloud involves the participation of a cross-functional team, including hundreds of developers, product owners, a few quality assurance-focused people, back-end engineers, a platform team, an API enablement team, and tech writers. These stakeholders have different roles at different stages of the process. To be successful, they must collaborate in an organized way, follow shared standards, and achieve common business goals—the hallmarks of a design-first strategy.
We spoke with Kostas Petrakis, the lead API engineer at Sendcloud with more than 20 years of experience in the technology world, to learn more about how they can do this.
Challenge One: Lack of Documentation & Consistency Throughout Their APIs
Petrakis and the API enablement team are tasked with ensuring proper API guidelines are set and followed throughout the API design process. This includes adequate quality testing, security standards, governance, and more, to ensure the company's APIs are consistent and high quality. One of the first challenges they faced was grappling with some APIs that were created nearly a decade ago.
"We wanted to enforce specific guidelines and improve our documentation because we were lacking in the documentation part, and our product is quite complex," said Petrakis.
To get started, Petrakis formed a small task force (which eventually evolved into the API enablement team that you see today), focused on identifying specific guidelines and tools to create consistency and scale their efforts.
The Solution: Stoplight Studio
The Sendcloud team understood early on that a team should be dedicated to enforcing the guidelines around their many APIs. In addition to the older APIs, a continuous stream of new ones were coming down the pipeline.
The team identified a need for a flexible and adaptable tool that could support a variety of different stakeholders in a cohesive process of designing (first) and documenting all of their APIs.
"That's where Stoplight came in, giving us a very wonderful way — with a studio client — of having developers quite easily document existing APIs, create missing endpoints from existing payloads, and more with open API specifications," said Petrakis.
The internal team was initially given a choice to stick to their editor of choice or try Stoplight. Very quickly, the majority of developers adopted Stoplight, indicating that it made documentation 'easier and faster.'
According to Petrakis, "Stoplight was integral in terms of the design and also for our public facing documentation which now all runs through Stoplight."
Challenge Two: Outdated Developer Portal & Poor Developer Experience
Their second problem centered on an outdated developer portal and poor developer experience. As the API enablement team started researching solutions, they figured out that Stoplight provided a portal solution as well.
Nearly every API that the Sendcloud team touched had input from multidisciplinary teams, but these teams lacked proper communication and collaboration resulting in a disjointed and clunky developer experience.
The Solution: Stoplight, Spectral & The Design First approach
Petrakis shared, "I can already say that using Stoplight was enlightening for our developers because it really helped quite a lot of our newer developers understand our product better." He continued "That, combined with the design-first approach, allowed us to rapidly design and prototype our APIs and move to the implementation phase quicker."
In particular, the Sencloud team appreciated the ease of integrating Stoplight with their repositories and the simplicity of engaging stakeholders. Stoplight helped various teammates from different disciplines easily use the tool and collaborate. Even among Sendcloud's less technically-skilled teammates and more junior developers, Stoplight was adopted quickly and effectively. In addition, prototyping APIs via Stoplight Platform's built-in mocking capabilities enabled developers and non-developers alike to try API designs against their public-facing services and easily share feedback before starting costly development.
"Stoplight allows our teams to work way faster. I would say you had to prototype through the code in the old days. Then, another team member would have to wait for the developer to finish their work to understand what exactly they needed to work on. Now by using Stoplight and adopting the design-first approach, we've already seen that there are features within Sendcloud that can reach the market way faster than before. It's now half of the time that was required in the old days," said Petrakis.
Another reason the Sendcloud team was drawn to Stoplight was that it helps API program leaders govern API contracts and specifications. The team utilizes Stoplight's open-source linting tool, Spectral, to ensure their API specs are properly set up.
"The design-first approach and using a tool that supports it eliminates the difficulty [in collaboration] and ensures that both worlds can work independently on the API but also with good communication and a foundational understanding of what's expected. Tools like Stoplight Studio bring this communication back to the forefront," said Petrakis.
Since adopting the design-first approach and Stoplight into their tech stack, Petrakis is happy to report that their entire organization has embraced the design-first mindset. They are now exploring how they can better treat APIs as products to stay competitive and adaptable in an ever-changing landscape. "APIs are not meant to be driven by developers. The product should drive them because the product is what shapes APIs. We very much believe in APIs as a product mindset," said Petrakis.
What's Next for Sendcloud?
There are two primary goals that the Sendcloud API team has set forth to accomplish. One is improving their documentation even further by involving more tech writers in their team.
The second goal is to improve the developer experience for public-facing consumers. This includes the generation of SDKs from open API specifications as part of that. Additionally, they plan to include more recipes on how their consumers can use their complex product and fully grasp actions they can take to ship something.
Petrakis concluded, "We've already started our journey with API virtualization, which is a scope for us to reduce the dependencies we have and carry over our old monolith era into a new era for Sendcloud."
For Petrakis, it's clear that the future is bright for APIs at Sendcloud.