Very good article on how using links in your API will enable you to build and
change your implementation more easily and get rid of the tedious documentation
task:
https://cloud.google.com/blog/products/application-development/api-design-why-you-should-use-links-not-keys-to-represent-relationships-in-apis