StopLight Launches a Modeling Suite to Design, Test and Document APIs
API software provider StopLight has launched a comprehensive tooling suite designed to manage all aspects of developing application programming interfaces, including design, testing and even documentation.
“How does a product manager at any given time know that their 400 endpoints are accurately documented and consistent? That’s what we are trying to help companies manage,” said StopLight founder Marc MacLeod.
Last year saw the API definition format file evolving to become the single point of truth for an enterprise. API definition formats are used to create a machine readable API specification that includes metadata information about a provider’s API. Popular formats include the Open API Initiative (previously known as Swagger), RAML, and API Blueprint.
API tooling platforms have put these definitions at the center of their lifecycle products, so that businesses can import a definition format file and have that automatically generate API documentation, facilitate testing and build SDKs. StopLight is trying to abstract that definition format file away so that end users — whether they be engineers, customer service support or business leads — can all work with the API from their own preferred (visual) interface.
MacLeod says by working within the constraints of HTTP, StopLight is able to create a visual tooling interface, which means more business roles can interact directly with the API, rather than having to understand a description format and be comfortable with making changes directly to the specification file. “With current tools, which are specialized text editors, the person doing the editing needs to know the spec pretty well,” warns MacLeod. “Instead, we have taken a more visual approach. You can manage hundreds of endpoints easily in a very visual way.” MacLeod gives the example of an API model that can be visually represented in StopLight but which would convert into a 16,000 line text specification in the OAI format.
“StopLight enables a single point of truth for an API: you manage it in one place, all documentation and tooling is around that single point of truth, it allows you to consolidate in one system,” says MacLeod. “Customer support staff, for example, don’t need to learn an API definition specification, and anyone can use and collaborate without having to learn a spec.”
MacLeod says the tool is aimed at any business trying to better organize their API strategy: “It helps businesses to build to the same standards, with a shared understanding of what their API is: How do they make sure their docs are always in sync, how do they ensure they have testing; the StopLight API Modeling Tool organizes all of these pieces, and makes sure everything is referencing the same definitions.”
API Modeling.
With today’s launch, the StopLight API tooling suite includes:
- API Designer, a modeling tool aimed at allowing developers and non-technical users collaborate on a business’ APIs
- Prism Proxy, an API proxy for testing the HTTP calls and responses for an API
- API-docs.io, a free hosted documentation tool that is able to be used independently, or can become part of the API Designer’s lifecycle, where various API versions can all be published out to the Docs platform.
While suited to mocking APIs for testing, MacLeod says the Prism Proxy component can also be used to reverse-engineer an API. For example, the tool can be used to map all the endpoints of an API, even if it is undocumented.
To date, MacLeod says the product has been tested with nearly 300 companies, predominantly working with API designers, but already the tool is finding a strong foothold with customer support.
API Tooling for Non-Technical Business Units
StopLight has fundamentally altered the API workflow across the SendGrid organization, particularly with the customer support department. said Matt Bernier, the Developer Experience Product Manager at API giant SendGrid, which uses APIs to send over 20 billion emails per month on behalf of Spotify, Uber, Foursquare, Airbnb and others.
“We had our customer-facing documents as our source of truth, but they were not written in the same language that our internal developers could use and edit,” explained Bernier. “So this is a nicer workflow. It takes out the extra learning: I don’t have to teach everyone what Swagger is because it is all visually represented in the model that Stoplight creates.”
StopLight saved SendGrid 10,000 support tickets a month, or 40 to 100 hours of work for staff.
“The big thing is that documentation describes how to use an API. Customer support people aren’t going to do some proxy magic and reverse engineer an API to know what the endpoints are. Our customer success managers work with our high volume customers,” Bernier said. “They don’t want to know how Swagger works, they don’t want to use cURL. Customers say to them, ‘I want to do this thing, can I do it with this API?’ Our people are not technical but with StopLight they can show our customers what to do quickly.”
Bernier says that if customer service can handle the query without escalating it, that avoids doubling the cost of support. He says with StopLight, the customer service team are able to generate an API key, make the API call, check the response, and then delete the key, all while speaking with the customer. Bernier has now mapped the previous support workflow against what StopLight enables.
“Our previous system was 35 seconds versus 10 seconds now. That saves 10,000 support tickets a month. That’s 40 to 100 hours of work saved for our entire support staff. It’s invaluable to SendGrid,” Bernier said.
Bernier said that he has had similar success showing engineering staff the three tools of StopLight, which means developers don’t need to switch between their current API tooling stack when moving between documentation and testing. “You can flip a window to see if the API is validated against the specification,” Bernier said.
One area of the tool he says he is keen to explore further is the reverse engineering capabilities of the Prism Proxy, which can take an undocumented API and map all of its endpoints. “That is the thing that I am most excited about. We use a lot of microservices, and inevitably, someone will need to work on some piece of code that only one person knew about. There is always that piece of undocumented code, people quit over stuff like that,” Bernier said.
Prison Proxy
API Documentation: Current Trends
Releasing the API-docs.io tool as part of StopLight and as a stand-alone product aligns with current discussions across the API economy, where API documentation is a growing industry consideration. In an interview on The New Stack last year, Phil Sturgeon, author of “Build APIs You Won’t Hate” said that if he was rewriting his API how-to manual, he would move documentation upfront as one of the first considerations in API design.
Last year also saw other API thought leaders push documentation as a central concern. API author and industry consultant James Higginbotham argues that an overall API documentation strategy creates a better developer experience; AXA Bank’s IT Architect Arnaud Lauret advocates for Documentation continuous delivery, and one of LinkedIn’s top 5 API documentation writers, Kelly Hitchcock says an API’s ‘proof of life’ is its documentation.
Already this year, new API documentation tooling being released has included Algolia’s open source search documentation tool DocSearch, while API mocking service Postman has offered a “Run in Postman” button to let API providers integrate Postman’s workflow and testing service directly into their documentation.
“Last year we saw some new API tooling platforms released that put the definition format at the center of the API lifecycle,” said Luke Miller from API Changelog, a service that helps developers identify when documentation changes for the APIs they are using.
“Alongside this, we saw tools like Lucybot and API Transformer make it easier to convert an API definition format file from one spec into another. The API economy realized that getting the description format right would help spur API growth,” Miller said. “Now we are seeing the next pain point emerge and getting solved: how to create and maintain consistent, high-quality API documentation. Just like the definition format was the single point of truth for creating the API, documentation is now being seen as the single point of truth for how people understand the API.”
StopLight’s API-docs.io offers one-click publishing to the hosting platform.
MacLeod says offering the new API-docs.io was a deliberate move to help spur growth across the API industry. “It was important to me to give the API community something meaningful and free, so the hosted docs will be free to use. My hope is that it becomes a convenient and robust alternative to Swagger UI when one needs a more complete solution,” says MacLeod.
While APIs are increasingly acknowledged as a business enabler for enterprise moving to offer digital services, and as a key tactic helping startups build out their ecosystems quickly, there can still be somewhat of a disconnect between what the API economy sees is happening and what the mainstream business world is experiencing. In truth, APIs are still in their nascency and while leading companies are taking up the API opportunity, many others — including governments, and traditional sectors like banking — are not yet really engaged. One of the core problems is the very term ‘API’ which hides the business benefits behind an IT term. Tools like StopLight’s visual editor, which can bring the API into a collaborative environment across technical and business team members are the start of what is needed next in order to spread API and digital transformation strategy throughout a business culture and strategy.
Feature image by Gabriel Santiago. Licensed under (CC 0 1.0).
