API Design Using Behavior Driven Development
By Justin Rohrman

Test-driven development (TDD) has been around for a while now.  Behavior-driven development (BDD), a comparably recent methodology, emerged from the practice of TDD and could reasonably be called a narrower application of TDD.

The TDD process allows a developer to use a failing unit test to express a shortcoming of the system.  The next step is to modify the production code to get the failing test to pass without making existing tests fail.  BDD more or less takes this same concept and adds the idea that the tests should be written in easy-to-understand language describing the problem domain, and that tests should express user acceptance criteria.

So instead of

void testErrorMessageOnNull()
you would have

Given a text box that has been left empty, when I click submit, I should receive an error message.
As a practice, this has found its way into the agile canon. It has given rise to something conversationally termed "three amigos," in which a representative of "the business," a tester, and a developer get together and agree on a few things: what the requested feature is, what it means, what it looks like when done, and how to verify completion.  In teams practicing BDD, the output of this conversation will often be an acceptance test, expressed in the Gherkin specification language.  When added to the codebase, this test will, of course, fail.  The folks implementing the feature know that they're done when they've succeeded in making the test pass.

If we put agile aside for a minute, this is a pretty commonsense approach for any team.  The essence of it is, "let's define and be clear about what success looks like and then automate a check for it."  So you don't need to be an agile team for this to make sense - you just need to be a team looking for clarity.

BDD in the API Provider World
Everything about BDD makes perfect sense in the line-of-business and traditional product development worlds.  In those worlds, "the business" wants stuff from "the geeks," and that basic operating paradigm creates the need for something like Gherkin to be necessary.  As elegant as it may seem, Gherkin could easily be viewed as pidgin developer-business talk.

But what happens when you're in the business of making products for developers?

I've worked with teams in the past that built a product with no user interface, to be consumed only by other software developers.  For teams like this, the people on and around the team may all have software development chops.  Testing is achieved through first-class programming automation.  People that function as project managers or business analysts are comfortable discussing the details of a method invocation or POSTing JSON to an endpoint.  The business is entirely technical, so there is no understanding deficit among the team members when talking shop.

So BDD doesn't apply for such teams, then, right?

Actually, it does.  In fact, I believe that it applies just as much to a project with technical consumers as it does to a project with business or public consumers.  And the reason for this is relatively simple.  While it may seem counterintuitive, BDD isn't ultimately about finding common ground in the language between "business people" and "geeks."  It's about being clear about what users can expect from a system, using terms both users and developers can agree on.

To be clearer about this, let's consider a problem domain for reselling tickets to events.  If we were building a website to be consumed by the public, we might write an acceptance test that's something like the following to drive system behavior:

Given there are 2 tickets available for the Rolling Stones Concert
When I request all tickets for the Rolling Stones Concert
Then I see 2 tickets
This test would call into the presentation/controller logic of the web application. It would seed the application with two available tickets, make a request for all tickets, and then verify that the two tickets were returned.

But what if there were no website? What if the product was just a backend service for a series of resellers to use to drive their own sites? In that case, our users would be the developers at those reseller companies. In that case, why not write a test like the following?

Given there are 2 tickets available for the Rolling Stones Concert
When I issue a GET to ~/concerts/RollingStonesConcert
Then I receive JSON with 2 ticket entries
Most people aren't used to Gherkin that looks like this, but it's perfectly valid.  The language is intended to describe your application's behavior in the terms of its domain.  And if your product is an API that provides this service, HTTP verbs, JSON, resource paths, and entries are part of your domain (along with tickets and concerts).

Representing Your Users
It's easy for us as programmers to become focused on the details of our system.  What's the performance like?  What should the preconditions and invariants be for this object instance?  Have we considered all the edge-case scenarios for this call?  And it's doubly easy to get caught up in these sorts of details when our users are fellow programmers who would be completely empathetic.

Don't get me wrong.  The details are important - very much so.  But the way users perceive and interact with your system is just as important, if not more so.  BDD forces you to think about that.  It forces you to form a common understanding of what success looks like with the people that are using your system.  The fact that you work on a technical product isn't a reason to pass on that opportunity. It's a reason to double down on it.

this didn't make sense to me the way it stood-"be written in language about ." I still don't know if it makes sense.