This is essentially the argument behind BDD, except applied at a level where the 'customer' is another developer. Some of the worst APIs I've seen have been on

This is essentially the argument behind BDD, except applied at a level where the 'customer' is another developer. Some of the worst APIs I've seen have been ones designed by a backend developer based upon some vague specifications handed down by a non-technical PO. They were often designed with half of the stuff that was necessary missing, lots of stuff that wasn't necessary and some stuff which made no sense before being thrown over a wall. The better APIs were 'designed' by the developer who would write the code that would consume them. Even if that just meant an email or a scrap of paper with a few example URLs and snippets of JSON.