Have a look at openAPI and decide whether we want to follow these specs

https://github.com/OAI/OpenAPI-Specification

For public and private APIs

---

Migrated from T1510 (view on Phabricator)