Specification should state whether the "default" fields for a type is required to be complete

[freddrake]

This has been discussed in the forum a few times, and the specification seems to be silent on this (at least in my reading).

It would be great if the specification explicitly stated whether the default set of fields returned for a type was required to include all available fields for the type.

Explicit is better than implicit.

[gabesullice]

The advantage of leaving it unspecified is that servers can choose to return no fields unless a fields query parameter is present. This is advantageous because a server can inspect its request log to identify which fields are depended upon and which could be safely removed. IOW, every field must be explicitly requested.

Perhaps a note like this would help?

Note: It is valid for a server to include no fields in its response unless the client explicitly requests them. This can reduce response sizes and help with server evolution—at the expense of discoverability and concision.

FWIW, even if we wanted to add a requirement about default fields, it would be an incompatible change that would require a new major version of the spec.

[freddrake]

I think a comment like that would be helpful. Specifying that the server can return a subset of the available fields when the client doesn't specify fields[type], and that an any subset is acceptable, would be best. That would cover both the case of needing to know what clients are using, and avoiding delivering expensive fields if not requested.

[gabesullice]

Care to open a PR? :) I think we can make the change in 1.0 and 1.1.

…

On Fri, Aug 7, 2020 at 9:05 AM Fred Drake ***@***.***> wrote: I think a comment like that would be helpful. Specifying that the server can return a subset of the available fields when the client doesn't specify fields[type], and that an any subset is acceptable, would be best. That would cover both the case of needing to know what clients are using, and avoiding delivering expensive fields if not requested. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#1499 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABCKWKK5DPNURQR2SAYSRJLR7P3ZVANCNFSM4PW7JOEA> .

[freddrake]

While working on this, it strikes me that the spec is also not specific regarding whether setting fields[type] to an empty string is allowed, in which case the client would be expecting no fields for each resource of the type.

Regarding the mechanics of making the change: Should I edit just one of 1.0, 1.1, and upcoming, or all of them? I didn't see anything about that in CONTRIBUTING.md.

[gabesullice]

it strikes me that the spec is also not specific regarding whether setting fields[type] to an empty string is allowed, in which case the client would be expecting no fields for each resource of the type.

Correct.

Should I edit just one of 1.0, 1.1, and upcoming, or all of them?

1.0 and 1.1. Upcoming is simply a redirect file.

[freddrake]

Resolved with the merge of #1500.

[gabesullice]

🙌