Skip to content

Why ”API first” really means API as part of a feature

For a while now, tech companies who develop online services have been successful at making their service easy to integrate by employing what is called an API first strategy. This lowers the barrier for other developers to build their own software on top of that service, which in turn may increase traction, visibility, and adoption.

Nowadays enterprises are starting to embrace the same idea, but there is a world of difference in how these two typically interpret and execute it.

The tech startup way:

  1. Start working on a feature
  2. Develop the API required by the feature (a few days)
  3. Develop the UI for the feature (a couple of days more)

The enterprise way:

  1. Conduct a pre-study to determine the full scope of the API to be implemented (2 months)
  2. Design the API in detail (4 months)
  3. Implement the API (6 months)
  4. Start building features on top of the API
  5. Realize that half of what would be needed is missing, and much of what was built is unnecessary


In my current assignment, I’m designing and building an enterprise-wide shared metadata management tool. Because we want to enable other enterprise applications to easily integrate with the shared metadata, we’re building it in an API first fashion. The tech startup way.

We’re developing the tool hand in hand with end-user concepts that utilize the metadata in our tool. And already with the first concept, we ended up redesigning that part of the API a couple of times. Imagine if we had spent a year to plan, define, and develop the API, only to realize, that it didn’t even provide everything our first feature needed.

This is why it often makes sense to couple your API design efforts with actual end user concepts or features, and to build the API piece by piece. Of course, for a very simple scenario, it may be possible to fully design your API without test driving it with the corresponding concepts. In my experience, though, enterprise IT seldom is that simple, and very few people, if any, are able to premeditate all the needs and corner cases you’ll encounter.