Relationship response example in website

[ekleinod]

Could you please provide an example for relationship responses in the examples section of the website, as this is really confusing for newbies of the spec. I did not grasp the difference in the response of xxx/relationship/yyy and xxx/yyy from the spec alone.

There is a great example here:

https://discuss.jsonapi.org/t/self-vs-related-links-and-what-to-return/1236/13

Maybe it is possible to copy that example, it was of great help for me.

Thanks for the spec 😁

[bradjones1]

Please open a PR.

[jelhan]

I also noticed that the difference between relationship links and related resource links is often confusing to people being new to the specification. I think mostly because most REST APIs do not support a concept, which is similar to relationship links. But to be honest I'm not sure if showing two different response payload in example would help much in that regard. Maybe a FAQ entry, which discusses the intent behind relationship links and what problems they address, may be more helpful?

The specification contains example response payloads for relationship links by the way:

json-api/_format/1.1/index.md

Lines 1137 to 1204 in 0f145e6

	For example, a `GET` request to a URL from a to-one relationship link could
	return:
	```http
	HTTP/1.1 200 OK
	Content-Type: application/vnd.api+json
	{
	"links": {
	"self": "/articles/1/relationships/author",
	"related": "/articles/1/author"
	},
	"data": {
	"type": "people",
	"id": "12"
	}
	}
	```
	If the above relationship is empty, then a `GET` request to the same URL would
	return:
	```http
	HTTP/1.1 200 OK
	Content-Type: application/vnd.api+json
	{
	"links": {
	"self": "/articles/1/relationships/author",
	"related": "/articles/1/author"
	},
	"data": null
	}
	```
	A `GET` request to a URL from a to-many relationship link could return:
	```http
	HTTP/1.1 200 OK
	Content-Type: application/vnd.api+json
	{
	"links": {
	"self": "/articles/1/relationships/tags",
	"related": "/articles/1/tags"
	},
	"data": [
	{ "type": "tags", "id": "2" },
	{ "type": "tags", "id": "3" }
	]
	}
	```
	If the above relationship is empty, then a `GET` request to the same URL would
	return:
	```http
	HTTP/1.1 200 OK
	Content-Type: application/vnd.api+json
	{
	"links": {
	"self": "/articles/1/relationships/tags",
	"related": "/articles/1/tags"
	},
	"data": []
	}
	```

It also contains examples how a relationship link could be used to update relationships: https://jsonapi.org/format/1.1/#crud-updating-relationships