Add suggested changes from API guild discussion (POST usage)

[SmilyOrg]

I took some liberties on the formatting/wording, but mostly it's as discussed in the internal doc.

[tkrop]

I'm a bit hesitant to approve this, because the pull request majorly splits up the dense description from before into 4 subsections without providing additional clarification that wasn't clear from the before context. In my opinion the deeper nesting is not preferable here.

The wording improvements are fine and could be added to the before structure too.

[SmilyOrg]

I'm a bit hesitant to approve this, because the pull request majorly splits up the dense description from before into 4 subsections without providing additional clarification that wasn't clear from the before context. In my opinion the deeper nesting is not preferable here.

The wording improvements are fine and could be added to the before structure too.

You're right, looking at it again it seems a bit too wordy. However, the previous dense description seemed a bit too overloaded, so there was a lot to interpret. Maybe there's a good structure somewhere in the middle? I'll have to take another look :)

Either way, I applied the suggestions, thanks!

[tfrauenstein]

👍

[SmilyOrg]

@tkrop this is ready for another look. Most of your comments were actually on a diff that was from a non-ideal merge, so I opened #795 for those. The diff should be cleaner now.

[tkrop]

👍

[SmilyOrg]

@ePaul I added your suggestion, please check again!

[SmilyOrg]

:+1:

[ePaul]

:+1: