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.
We are actively working on the REST API and Graph API documentation improvements, but as this issue does not have clear explicit delivery criteria, we are closing it to ensure that it does not hide any other critical gap with more specific delivery details.
We are highly interested on improving the documentation and are absolutely open for suggestions, but also want to ensure that the votes are available for more concrete submissions.
Setting status as closed as we definitely are not declining this and are actively working on it, but would not consider it also as “done”.