Using a Prototype as an API Product Specification

As the Developer Experience Product Manager at MailCot, 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, Engineers, and customers more effective.
I have learned that a Mailcot Product Requirements Document 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 is that they are often very large and mostly text. It is too easy to lose your place or miss something really important.

Using a Prototype as an API Product Specification

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 document.

Other Specification –

  • First of all, 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
  • Also, There needs to be a single master representation of the spec to reduce ambiguity and versionitis.
  • My requirements for prototype-as-specification:
  • The prototype should be the spec.
  • Also, The documentation should be integrated into the prototype.
  • Everyone in the company who needs it should have access to the prototype and documentation.
  • And also, 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.
  • First, 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.