REST API citizenship! (surface, roadmap and change log)
Besides the lack of detailed documentation around the REST API, given its importance as a major entry point for apps, it needs to be treated with more respect as a service offering. It's currently being updated in CUs and on SharePoint online without any notification of the changes being made (such as the $metadata endpoint appearing - was it in the August 2013 CU for on-prem?). We either need it to be released in a non-breaking change model (URL versioning such as the Twilio model), or messaging needs to be improved so we know when things are going to be changed. Having a log of changes that have been made to date would be helpful, along with understanding what changes are currently in the queue. For example, I would LOVE to know if the end game for the _api endpoint is to finally be a first-class OData v3 endpoint sometime soon.
Thank you for your input. REST APIs are absolutely critical for the SharePoint Framework and for other customizations. We are working on improving the existing documentation and to ensure that you can more efficiently take advantage of the SharePoint REST APIs in your development.