Add documentation for REST link relations

Problem/Motivation

There is no human readable documentation for a REST API.

Proposed resolution

Provide documentation for link relations. For example, see http://haltalk.herokuapp.com/rels/posts. When a site enables HAL, this documentation can be used to guide users through the API... see HAL Browser for HAL Talk.

Some APIs to XREF our new one.

• http://developer.wordpress.com/docs/api/
• https://dev.twitter.com/docs/api/1.1
• https://developers.facebook.com/docs/graph-api/reference/v2.0

How to test

1. http://drupal.d8/admin/help/rest follow link to API
2. http://drupal.d8/docs/rest/api
3. http://drupal.d8/docs/rest/api/types/node/article
4. http://drupal.d8/rest/relation/node/article/title

Remaining tasks

• Checkout https://www.drupal.org/project/services_docs to see what can be used esp. UX parts if any.
• Fix the code TODOs
• Check with #2282029: Automate link relationship headers and #2113345: Define a mechanism for custom link relationships
• Should we introduce an API version? Do we need an API version? Currently moved routes into /api
• What to expose to whom? Should there be a 'Read API' permission? How to handle field permissions?
• The permissions are on entity/bundle ... why is rest not exposing similar?
• The chosen and dictated path do not match. Where should the Rest API documentation land? Our idea is under:
  1. /api/rest (list of resources) currently list bundle too.
  2. /api/rest/entity_type (list of bundle)
  3. /api/rest/entity_type/bundle (list of fields)
  4. /api/rest/entity_type/bundle/field_name (list of field properties)
• Using https://github.com/mikekelly/hal-browser the documentation relation fields documentation work aka http://drupal.d8/rest/relation/node/article/uid ... we still don't get that links 'relation' part. Documentation for _embed using hal-browser are properly mapped aka http://drupal.d8/rest/relation/node/article/field_image

Code TODOs

ResourceRoutes.php
(103, 6) * TODO: why do we generate routes for relations?
(110, 8) // TODO: why filter out the non relation ones? Ie field_image is exposed through _links to ie HAL browser.
(119, 12) // FIXME
(122, 16) // TODO why use relation in link. This should be in */api/* path
(165, 8) // TODO: Change this to only expose info for REST enabled entity types.
(166, 8) // TODO: filter out all ConfigEntities

Controller.php
(15, 6) // TODO use DiC
(124, 8) // TODO fix for drupal_set_title
(133, 8) // TODO: SA what information is disclosed?
(135, 8) // TODO: how to check for field permissions?
(157, 8) // TODO use DIC
(162, 8) // TODO: Change this to only expose info for REST enabled entity types.
(169, 8) // TODO use DIC

User interface changes

API changes

Original report by @linclark