Immutables

[hhware]

Proposing support for members immutable in attempt to resolve #575.

I am cutting corners here: this PR in its current form assumes that #588 is accepted, and hence should not go ahead of #588. I want to throw it in anyway because not so much time is left before 1.0.

[hhware]

I think it would be better to use the term unmodifiable: their modification via API is not allowed, but their values can be of course changed by server...

[cziegenberg]

I'd say that "immutable" is okay, although it doesn't describe the state of the resource object but of its attributes here.

And it's clear, that this is an information for the client only and that it doesn't limit the server in modifying the resource attributes.

[bintoro]

There's actually a term for this: "read-only".

[cziegenberg]

All words express the same and all still mean that the server can modify it anyway... :)

[hhware]

Updated the PR:

• replaced immutable with readonly
• added 403

[hhware]

Updated: added a clause about accuracy for client / resource / moment in time, similar to one in #590.

[pixelhandler]

@hhware perhaps this additional spec can be achieved using the meta section of the payload, rather than defining additional structure. I had considered something similar for "protected-attributes" as a sibling of "attributes" but the more I thought about it I'm happy with expressing that level of detail as meta content, see #575 (comment)

[hhware]

@pixelhandler, this is what I initially thought about it (#575 (comment)), but then I concluded that it could have broader audience than just one API: meta is intended for custom stuff, specific to a given API...

[dgeb]

Given that both attributes and relationships may be read-only, I'm opposed to a common bucket that could group both together purely from a structural perspective.

I think it's also important to realize that immutability can be temporal, and that attributes that are read-only at the time of one request may be mutable at a later time due to a resource's change in state.

[hhware]

Given that both attributes and relationships may be read-only, I'm opposed to a common bucket that could group both together purely from a structural perspective.

But on the other hand, they share the namespace. IMHO, this is strong enough commonality to allow them to be listed together in a common bucket. I would no mind separating them in different sub-buckets though, if that helps.

I think it's also important to realize that immutability can be temporal, and that attributes that are read-only at the time of one request may be mutable at a later time due to a resource's change in state.

Is not it an argument in favor of having such mechanism? Many things about resource can be temporal: its existence, its representation in any given response, immutability of some members. Temporal aspect can be handled via resource versioning.

[jelhan]

I think this could be very well solved using an extension available in v1.1. An extension does not require changes to base spec. This should allow experiments and quicker iteration than trying to add it to main spec.

[bednic]

I like this 👍