Clarify the correct ways to differentiate different behavioral modes of API resources

[pmorie]

We've had a number of questions during API design for service-catalog about using magic values. I believe the prevailing consensus amongst the owners of the project is that magic values in APIs are undesirable, but the API convention document does not give any treatment to this topic. Varations of how this has come up:

• Magic values for the names of objects as used in reference; ie, when a field that holds a reference to a k8s resource takes on a special value, the behavior of the enclosing resource changes
• Magic values for non-reference fields

I think it would be great to document this and get clarity for newcomers to the project, but would like to see some agreement in this issue before I file a PR.

[derekwaynecarr]

can you give an example magic value?

[pmorie]

@derekwaynecarr a couple specific examples:

1. When a reference field has the magic name (k8s-magic-thing), the behavior of the resource with the reference field completely changes
2. When a field holding a duration has a zero-value, it means 'never' (this one might actually be okay, but i'm not sure if I'm remembering this one accurately)

[deads2k]

When a reference field has the magic name (k8s-magic-thing), the behavior of the resource with the reference field completely changes

The behavior of resources should be consistent and predictable. We do have some APIs which have flavors, but are overall consistent in intent and handling. There are two approaches to doing this:

1. type. This is done with Services in the ServiceSpec.Type field. It is a strict enumeration of allow types which can flavor the behavior, but the overall thing is always a service. It always behaves as a service and the field is dedicated to only flavoring it.
2. one of many pointers. This is done with volumes in the VolumeSource type. There are many concrete flavors of volumesource, but only one may be set in the object. Again, these always behave as volumesources and this is simply choosing a subtype.

When a field holding a duration has a zero-value, it means 'never' (this one might actually be okay, but i'm not sure if I'm remembering this one accurately)

Deciding how to handle default values for objects with default behavior that works in the majority of cases is a case-by-case decision. I don't think I'd want to dictate how people handle it, although "never timeout" usually isn't a good default, so the behavior there seems undesirable.

[deads2k]

Oh and I should say that having been through this in several APIs, I think the approach of "on of many pointers" ends up working better since it allows specific descriptions of what you want and makes future growth easy.

[pmorie]

The behavior of resources should be consistent and predictable. We do have some APIs which have flavors, but are overall consistent in intent and handling. There are two approaches to doing this:

Yep, and those two approaches should be sufficient to differentiate behaviors of resources where necessary

[bgrant0607]

See also:
kubernetes/kubernetes#35345
kubernetes/kubernetes#6979

[bgrant0607]

Magic values sound evil

[bgrant0607]

The API conventions do state the following:

The term "type" should be used for distinguishing sub-categories within objects or subobjects.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

Prevent issues from auto-closing with an /lifecycle frozen comment.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or @fejta.
/lifecycle stale

[bgrant0607]

/remove-lifecycle stale