Add docs about  hypermedia

looks nice, but what do you think about remove the code comments 
and add a simple paragraph explaining this just after this block code?