Make self links optional

[pvdbosch]

Propose to make "self" links OPTIONAL ("MAY") instead of RECOMMENDED ("SHOULD").

Current guideline: Each resource SHOULD also contain its own location in a self attribute at root level of the JSON document.

Self links don't seem frequently provided by APIs however, nor used that much. They also require a modification in the code on each provided resource.

[JDMKSZ]

I don't know if it's relevant to make a distinction between different scenario's?

• GET /collection/id: when getting a resource, a self link is irrelevant, you already should know the URL
• POST /collection: when creating a resource though, it might be interesting to have the URL to the new created resource, although the resource also contains its ID so it should be
• GET /collection?param=x: for collections it might make more sense e.g. when using query parameters and/or pagination, but then again, normally you're already aware of the URL just used

[pvdbosch]

The response of a resource created using a POST on a collection resource should have a Location HTTP header that points to the newly created resource, so also not really needed there.

If using "self" in this case, the guide isn't very clear that it should be the URL of the collection resource or the one of the new resource. In the long-running task example, the collection resource URL is specified.

[pvdbosch]

WG is in full agreement to make optional

[pvdbosch]

new version of guide is published with the change