diff options
| author | Yusuke Tsutsumi <yusuke@tsutsumi.io> | 2021-06-13 20:00:24 -0700 |
|---|---|---|
| committer | Yusuke Tsutsumi <yusuke@tsutsumi.io> | 2021-06-18 13:46:40 -0700 |
| commit | 00d73216d377870f851a07dddef0bbe6265ad593 (patch) | |
| tree | 106ef1b7244111258ae543d3c7297f52d1cc7eef | |
| parent | fc4656b9344c7b2f8aff2c4f74d4867f811671b4 (diff) | |
consolidate object ref guidance in api conventions
API conventions had two semi-duplicated sections for
object references, with slightly different guidance.
Consolidating guidance to point to the most recent
guidance.
Clarifying the naming recommendations for naming of lists
of object references, as the guidance was not explicit.
| -rw-r--r-- | contributors/devel/sig-architecture/api-conventions.md | 9 |
1 files changed, 4 insertions, 5 deletions
diff --git a/contributors/devel/sig-architecture/api-conventions.md b/contributors/devel/sig-architecture/api-conventions.md index 5c4c4a21..c1f72ce8 100644 --- a/contributors/devel/sig-architecture/api-conventions.md +++ b/contributors/devel/sig-architecture/api-conventions.md @@ -479,11 +479,7 @@ ensure that GETs of individual objects remain bounded in time and space, these sets may be queried via separate API queries, but will not be expanded in the referring object's status. -References to specific objects, especially specific resource versions and/or -specific fields of those objects, are specified using the `ObjectReference` type -(or other types representing strict subsets of it). Unlike partial URLs, the -ObjectReference type facilitates flexible defaulting of fields from the -referring object or other contextual information. +For references to specific objects, see [Object references](#object-references). References in the status of the referee to the referrer may be permitted, when the references are one-to-one and do not need to be frequently updated, @@ -906,6 +902,9 @@ It is okay to have the "{field}" component indicate the resource type. For examp a secret. However, this comes with the risk of the field being a misnomer in the case that the field is expanded to reference more than one type. +In the case of a list of object references, the field should be of the format "{field}Refs", with the same guidance +as the singular case above. + ### Referencing resources with multiple versions Most resources will have multiple versions. For example, core resources |