> Resource links aren't a part of the resource.

Then why are the single most important and widespread form of resource links, HTML URLs, always included in the response body i.e. in the HTML document itself?

HTML is a markup language whose primary goal is to provide human users with a readable and navigatable document through a web browser.

There's a reason why HTML is primarily used to provide human-readable documents, while web APIs are implemented based on other document formats that are better suited to provide machine-readable resource encodings.

Let me explain why you have reached the wrong conclusion. The key is to think about why the markup is needed. Is it to format documents, to make them 'readable'? No, it's to tag documents with semantic meaning that computers can use to enable richer content and behaviours. That's why, for example, tags like `<b>` and `<i>` are nowadays widely accepted to be design mistakes in HTML, and we use CSS instead for formatting. That's why we encourage semantic markup like `<section>`, `<nav>`, and even `<div>`.

Hyperlinks are one of the basic semantic markup tags. They allow machines to read them and insert jump points. The key here is that they are machine readable to enable behaviour that wouldn't be possible otherwise.

Right.. so... that doesn't jibe with how the real world thinks about these things. In the real world we want the pet to have an "owner" attribute, which is part of the resource.

The real world is outside Google and (at least try to) follows the RFC standard.

The pet does have an owner. It's another resource, however, whose location can and does change.

You should just know that this makes zero sense to most of us. Either that's because it makes no sense, or you can't explain it well, or we're all too stupid to get it. Either way, good luck with that "standard".

> You should just know that this makes zero sense to most of us.

Unless you've held an election, you only speak on behalf of yourself and yourself alone. If you're having a hard time understanding basic concepts then naturally it's unlikely that you'll have an epiphany in a discussion where you're decided to take an hostile stance towards details you're not understanding.

Meanwhile, you can ponder how these specifications you're claiming you and those you claim to be representing don't understand are actually used extensively, and it's such a basic concept that it even features in intro tutorials to REST APIs. Perhaps that's a good sign that basic concepts such as web linking aren't that complex or hard to understand as you've tried to assert they are.

https://restfulapi.net/hateoas/

They provide what you've described as an alternative to what most consider the normal way of representing resource links. It doesn't make any of the claims you are making as to why one is more valid than others.

So once more: sure we can do things your way, but why is it better? Every other source says link headers are an option. You claim they're superior. Why are they better?

Why does representing links in headers and not bodies make the API easier to understand, navigate, or use? How does it clarify the interactions? What do I gain from it?

So far, all you've said is "relationships are metadata" or something, which is not how most people consider relationships, and even if it we're true, it doesn't explain why my response can't contain metadata, as long as it's marked as such.

I've built actual HATEOAS services for a few years now, and I work/chat with several people that do the same, including a few authors on this subject, and I don't think that the idea that "a relationship generally should not be part of the representation itself, because it's meta-data" is a very universal idea. I'd say far from it.

Aside from that, I'm curious how do you manage alowing API clients to create new relationships or change them?

> Aside from that, I'm curious how do you manage alowing API clients to create new relationships or change them?

What's hard to understand? If you add a resource then you update your link relations. If you actually tried to implement a REST API instead of RPC-over-HTTP then the client navigates link relations just as before. That's pretty much the whole basic premise of REST.

The thing I'm mostly curious about is situations where a client manages relationships. For example, you already have an 'article' resource and now want to add a new 'category' link to that article. Clients often need to be able to create new relationships, or perhaps remove them. I'm curious if you ran into this and if so, how you do this with just Link headers.