Using a Prototype as an API Product Specification

As the Developer Experience Product Manager at SendGrid, I am tasked with identifying opportunities, features, and products that involve our API. One thing I have been working on is identifying methods to make communicating my product ideas to the other PMs, Engineers, and customers more effective.

I have learned that a monolithic Product Requirements Document (PRD) is a less than ideal way to do this and that a testable interface including the same information as a product specification would be a powerful alternative. The problem with PRDs is that they are often very large and mostly text. It is too easy to lose your place or miss something really important.

Our friends in UX have solved this problem with tools like Invision, where they provide a clickable interface that you can touch and use, rather than a document or wireframe that simply describes the interface. Since an API is an interface, we need a tool that will allow interaction with the specification in real time, rather than a bunch of descriptive text and JSON in a document.

Defining Requirements

What should this testable interface as a product specification look like? How would it work? Does it exist?

As I was reading Chapter 18, “Reinventing the Product Spec,” of Marty Cagan’s Inspired: How to Build Products Customers Love, I realized that I wanted to share a tool I have been using that satisfies Cagan’s requirements for a product spec, most of his wishlist for product spec, and my own personal list of prototype-as-a-specification requirements.

Cagan’s requirements*:

• The spec must describe the full user experience.
• The spec must accurately represent the behavior of the software.
• You must be able to communicate the product in a way that all stakeholders get what they need.
• The spec will change
• There needs to be a single master representation of the spec to reduce ambiguity and versionitis.

Cagan’s wish list*:

• You will need to supplement the prototype [with]:
  • Business logic
  • Release requirements
  • Platform delivery requirements
  • Use cases
• I really want to be able to annotate the prototype

My requirements for prototype-as-specification:

• The prototype should be the spec.
• The documentation should be integrated into the prototype.
• Everyone in the company who needs it should have access to the prototype and documentation.
• The customer should be able to access the functional part of the prototype for user testing.
• The prototype should replace the spec and work as close to the intended functionality without wiring up a finished product.
• It should be easy to make and record changes to the prototype.
• It should be easy to make A/B variations which can be tested by anyone with access to the prototype.
• It should be easy to export the customer documentation from the prototype.

Introducing StopLight

The tool that I have been using that satisfies nearly everything above is called Stoplight.io. It is at its core an API documentation engine and web proxy. It allows you to define your API using an intuitive UI, which has the best of both Swagger and RAML behind the scenes as its specification engine along with the ability to import or export from either format.

Since StopLight is a documentation tool, you can define the requests, responses, headers, and descriptions for your endpoints. With the proxy feature, you can call your API and verify that your calls match your specification or autodiscover your endpoints to get most of your documentation written automatically.

StopLight’s proxy also has several other absolutely amazing features:

• The ability to make mock calls to your endpoints if your product isn’t finished or you do not want to proxy your requests.
• Local server for testing your prototype on your machine.
• Remote server for testing your prototype out on the Internet.
• Middleware, written in Javascript, for defining code that can run before and/or after your prototype’s endpoints are called.

If you compare the combination of my wish list, Cagan’s specification requirements, and his wish list to the functionality that StopLight provides, you can see that StopLight satisfies every need and desire:

• Internal-only documentation of the prototype and its features.
• An easily accessible full prototype of the functionality.
• A testable interface that has the ability to toggle variable features for user testing and feedback.
• An easy way to version your prototype for a specific conversation, so that you can modify the functionality of the prototype in near real-time to illustrate and verify the feedback you’ve received.

The workflow in StopLight is simple and can be done by anyone, regardless of their technical ability:

• Create a new project.
• Add the specification by clicking and typing information about the endpoint, its parameters, request, and response.
• Add in the specification information about your prototype in the Definition screen.
• If you have optional features, add them in using the middleware.
• Turn on mocking.
• Copy/paste the public URL for the mocking server and share this for feedback.

If you’re going on a customer visit and would like to experiment with the prototype in real time, simply download the definition to your computer, create a new project named after your visit, and import the definition. Now you can change anything you want without changing your original prototype. When you’re back and merging ideas, it’s as easy to make changes as it was to build the prototype in the first place.

As the Developer Experience Product Manager, StopLight is not only helping me to do my job more efficiently, it is dead simple to use, and makes the delivery preparations steps of documenting the API easy since the documentation was started before customer validation steps and is updated throughout the process. There are many other use cases and features that StopLight provides, but this may be the one that has impacted my job the most significantly.

---

*Cagan’s requirements and wishlist are direct quotes from Inspired: How to Build Products Customers Love.