Can someone explain the @RestResource annotation for building a Rest resource?
Annotations are used in Drupal 8 to provide meta data in the same location as the class definition. It was borrowed directly from Symfony which is used in the Drupal 8 core to take advantage of an existing framework. The meta data is contained from the lines between @RestResource( and the closing ). Everything else is treated as a normal php block comment. For example I have a custom REST resource for which the annotation is:

/**
 * Provides a resource for database intermed table entries.
 *
 * @RestResource(
 *   id = "intermed",
 *   label = @Translation("Intermed content entity standard methods"),
 *   serialization_class = "Drupal\intermed\Entity\Intermed",
 *   uri_paths = {
 *     "canonical" = "/intermed/{intermed}",
 *     "http://drupal.org/link-relations/create" = "/entity/intermed"
 *   }
 * )
 */


So for this resource intermed is the id and is used in request operations. The canonical form /intermed/{intermed} will be used for operations other than POST which uses /entity/intermed

In the canonical setting the {intermed} denotes a parameter to be passed.

So if I was to send a GET request to site d8beta14.qetm.org as format HAL+JSON for the intermed table entry for which the id was 2:

GET http://d8beta14.qetm.org/intermed/2?_format=hal_json

This GET operation requires three headers: Authorization, Accept, Content-Type