"Designing" connectors

  • 17 May 2022
  • 1 reply

Userlevel 1

Hi, I’ve been asked to Spec/Design a connector between our product and an external system.  Put simply, it’s an API-API connector.

The complication is that the configuration on both systems could be different for each customer.

We work in an agile development methodology, so I don’t want to write a 100+ page spec that nobody will read.

If this was a more typical area of the product, I’d start by identifying users and jobs to be done, and then creating some wireframes.

In this case, there are no users (System-System), and there are very few screens beyond the configuration screen, I guess. Even if I did spec/wireframe these, I’d only be covering 5% of the functionality.

I’m a bit stuck TBH - looking for ideas for how to start.


1 reply

Userlevel 7
Badge +12


Is the external system one that you own and operate or one that your customers own and operate?

When building an API it’s worth you going out and exploring what needs/problems/jobs your customers need to be able to accomplish with your API and how it should/could be configured so you can find the common use cases across each configuration. It’s also worth spending some time getting your customers to prioritize, but to also consider who’s most likely to create this connection and where you can best direct your energy and focus.

Overall I’d build it iteratively, do a beta with some of your customers and potential early adopters to get feedback, and use that to help you define the documentation and other support materials your customers should need.

@JeremyAlexander who handles our API here at Productboard may also have some perspectives to share (or counterpoints to my thinking and experiences).