Quite many experienced API developers prefer to start from the end eg from documentation. Next to it is mockup API which is tested with sample code to see how it feels in everyday usage. The sample codes can be used in the API documentation after everyone involved is satisfied.
The above 3-column documentation (top) is also the one used by Stripe. In that case it’s a detailed collection of information regarding endpoints, error situations and authentication. Not all documentations with similar structure are alike. For example Todoist uses the same documentation structure, but in their case it’s more like a story which guides you through common workflows in the app.
If you happen to use Postman already, they have tools to generate 3-column documentation for your API. If you need to build same result under your brand (style and all), then you might want to use open source solutions such as Slate.
Of course documentation can be different and more robust solutions than the praised 3-column will occur. Regardless of the style you choose, the overall process most likely will be the same: documentation — mockup — sample test code.
In some cases you are not able to add dynamic code execution features to the documentation. In that case, just leave it out and provide the example codes for selected programming languages. The API consumer can then select (copy-paste) the code to wanted environment and continue testing there.
Build for Developers -book published 2019
More about the subject will be in Build for Developer -book, which is due to be published 2019. Read more from: