Any objections to my merging this?

The wording is slightly awkward, but I am fine with this 👍

Cool beans; merged. Re the wording, I'm happy to revise it if anyone has ideas. In the mean time, though, I figure something is better than nothing.

I think the wording of the added part is fine; however, I've always thought the previous sentence is unhelpful:

For example, it would allow a client to remove an author from an article without deleting the people resource itself.

Surely you don't need to go through the relationship URL to do that — just set the value to null. So if someone revisits this part, that explanation is what I think could use some improvement.

In #498 I suggested:

For example, it would allow a client to add a new comment to an article without going through the article resource and updating the entire set of comments references.

Looking at this now, "replacing the entire set of comments references" would be even better.

Nice to see you again, @bintoro! Hope all's going well :)

About the sentence you mentioned: I've always understood its chief purpose to be pointing out the difference between updating resource objects and updating the links between them. Your text better captures when exactly a relationship link would be needed (since, as you point out, the example currently given could be handled through the resource object), but it seems to bury this high-level distinction a bit. Maybe there's some text that gets the best of both worlds?

Well hey @ethanresnick 😄

I had to take some time off coding because of vision problems that turned out to be a tumor messing with the optic nerve! It got taken out and now I'm recovered. 💪

About the sentence you mentioned: I've always understood its chief purpose to be pointing out the difference between updating resource objects and updating the links between them.

Ahh okay now I get it. I've always read it as if it's trying to present a way to do something fancy:

For example, it would allow a client to remove an author from an article without deleting the people resource itself.

Rewriting it like this totally changes the connotation for me:

For example, deleting an author through an article's relationship URL would break the relationship without deleting the people resource itself.

To me, this looks more like a description of what the link is, as opposed to an example of something cool the link can do. Am I making any sense here?

@bintoro Sorry to hear about the vision issues, and so glad you're recovered!

To me, this looks more like a description of what the link is, as opposed to an example of something cool the link can do. Am I making any sense here?

Yeah, that makes total sense, and I'm 👍 on the spirit of your wording, though I'd tweak it a bit:

For example, removing an author through an article's relationship URL would disconnect the person from the article without deleting the people resource itself.

Does that sound good? If so, can you open a PR and, assuming no one objects, we'll merge it in!

removing an author through an article's relationship URL would disconnect the person [...]

Yessss, that's the word I was going for. Perfect.