Clarify query parameters for top-level self link

jelhan · web-flow · commit 41baf41aeaba · 2022-01-30T11:11:55.000+01:00
In the past we have seen several questions regarding the top-level `self` link and if it should contain query parameters supplied by the client, which affected the response document. Adding an explicit note about it should help to prevent such confusion in the future.
diff --git a/_format/1.1/index.md b/_format/1.1/index.md
@@ -319,6 +319,12 @@ The top-level [links object][links] **MAY** contain the following members:
   Schema) for the current document.
 * [pagination] links for the primary data.
 
+> Note: The `self` link should contain the query parameters provided by the client
+> to generate the current response document. This includes but is not limited to
+> query parameters used for [inclusion of related resources][fetching resources],
+> [sparse fieldsets][fetching sparse fieldsets], [sorting][fetching sorting],
+> [pagination][fetching pagination] and [filtering][fetching filtering].
+
 The document's "primary data" is a representation of the resource or collection
 of resources targeted by a request.
 
