API Spec: where should it be?

TL;DR: The API definition and documentation must be in a separate repository.

Introduction

In the desktop or CLI apps era, you probably only had one folder where you would put all your code.

When the CVS arrived, you put that folder in version control.