Merge branch 'sh-clarify-graphql' into 'master'

Clarify API V5 being a compatability layer on top of GraphQL

See merge request !12030

doc/api/README.md

@@ -57,12 +57,16 @@ following locations:
 
 ## Road to GraphQL
 
-API v4 will be the last REST API that we support. Going forward, we will start
-on moving to GraphQL and deprecate the use of controller-specific
-endpoints. GraphQL has a number of benefits:
+Going forward, we will start on moving to
+[GraphQL](http://graphql.org/learn/best-practices/) and deprecate the use of
+controller-specific endpoints. GraphQL has a number of benefits:
 
 1. We avoid having to maintain two different APIs.
 2. Callers of the API can request only what they need.
+3. It is versioned by default.
+
+It will co-exist with the current V4 REST API. If we have a V5 API, this should be
+compatability layer on top of GraphQL.
 
 ### Internal CI API