Consider using this format:
https://developers.google.com/+/api/#partial-response

Another reference:
https://blog.apigee.com/detail/restful_api_design_can_your_api_give_developers_just_the_information

I like the Google+ ?fields parameter.

I like xpath style better than JavaScript dot notation, and think in general it serves better for query/selection of a subset of a document. The event FieldPath and validation field selectors would then just be the singular case.

http://goessner.net/articles/JsonPath/

On Sat, Sep 27, 2014 at 7:20 AM, Clayton Coleman [email protected]
wrote:

I like xpath style better than JavaScript dot notation, and think in
general it serves better for query/selection of a subset of a document. The
event FieldPath and validation field selectors would then just be the
singular case.

—
Reply to this email directly or view it on GitHub
#1459 (comment)
.

I immediately retract my statement and return to my original position. Dots ftw :)

----- Original Message -----

http://goessner.net/articles/JsonPath/

On Sat, Sep 27, 2014 at 7:20 AM, Clayton Coleman [email protected]
wrote:

I like xpath style better than JavaScript dot notation, and think in
general it serves better for query/selection of a subset of a document. The
event FieldPath and validation field selectors would then just be the
singular case.

—
Reply to this email directly or view it on GitHub
#1459 (comment)
.

---

Reply to this email directly or view it on GitHub:
#1459 (comment)

The Google+ ?fields format lets you select multiple fields, and at multiple points in the hierarchy, in a compact fashion. This seems pretty useful. Can "dots" format do this?

URL parameters can be specified multiple times if we need to select multiple fields.

Would we need to use the multi-field selection format inside of resources (i.e. ComponentReference or Validation errors)? I don't think so, which would mean we'd want the selector on in url params to be a superset of that selector inside the fields.

----- Original Message -----

URL parameters can be specified multiple times if we need to select multiple
fields.

---

Reply to this email directly or view it on GitHub:
#1459 (comment)

After consulting with internal experts on this area, I think we should do the following:

• keep it very simple
  • rationale: there will be a number of clients that need this, so don't make them use a library to deal with this stuff.
• syntax is dot separated property names, such as a.b.c
• used for projection in GET request (?fields=a.b.c)
• can specify multiple of these with comma-separation (?fields=a.b.c,a.d.e.f)
• applies separately to each item in a LIST operation (cannot mask properties of the list itself, if such exist)
• no provision for selecting an index out of an array.
  • Rationale: don't introduce indexes as a way to identify entities. We use names for that. If we need to talk about containers in isolation, then we should have a distinct resource path to them, like /pods/xyz/container/abc, where abc could be mapped to/from pods.currentState.manifest.container.name.
• If there are arrays then the array has to be the last item in the dot-separated sequence.
  • Rationale: KISS
• this syntax could be used in PATCH, if we want to implement that, to specify which fields to update.
• this syntax could be used (hand waving) to specify which fields of a pod template that a controller was allowed to modify?

----- Original Message -----

After consulting with internal experts on this area, I think we should do the
following:

• keep it very simple
  • rationale: there will be a number of clients that need this, so don't
    make them use a library to deal with this stuff.
• syntax is dot separated property names, such as a.b.c
• used for projection in GET request (?fields=a.b.c)
• can specify multiple of these with comma-separation
  (?fields=a.b.c,a.d.e.f)
• applies separately to each item in a LIST operation (cannot mask properties
  of the list itself, if such exist)
• no provision for selecting an index out of an array.
  • Rationale: don't introduce indexes as a way to identify entities. We use
    names for that. If we need to talk about containers in isolation, then we
    should have a distinct resource path to them, like
    /pods/xyz/container/abc, where abc could be mapped to/from
    pods.currentState.manifest.container.name.
• If there are arrays then the array has to be the last item in the
  dot-separated sequence.

I think we need to support this for validations. If I submit a pod with 5 containers and one of them has a missing attribute clients have no way to determine that. So maybe we say that it's not allowed in any context except for validations. I am extremely sensitive to building good UI experiences around default validations provided by the platform though so I have a strong bias. Is there another way to do validation on specific fields that means clients don't have to guess what failed?

• Rationale: KISS
  • this syntax could be used in PATCH, if we want to implement that, to
    specify which fields to update.

+1

• this syntax could be used (hand waving) to specify which fields of a pod
  template that a controller was allowed to modify?

+1

I see this as about specifying fields in an URL. If an HTTP request to create or update a resource fails, there is no URL to refer to on the apiserver. I think using a format with indexes in a non-URL error message or other context seems fine.

Ok, then latest proposal LGTM

----- Original Message -----

I see this as about specifying fields in an URL. If an HTTP request to
create or update a resource fails, there is no URL to refer to on the
apiserver. I think using a format with indexes in a non-URL error message
or other context seems fine.

---

Reply to this email directly or view it on GitHub:
#1459 (comment)

For reference: https://blog.apigee.com/detail/restful_api_design_can_your_api_give_developers_just_the_information

What is the rationale for using dot approach and not just the Google+ API method exactly?

JavaScript. Anyone who has to do field validation or jquery or jq will be able to leverage that format. The others are somewhat ivory tower

Is that still true with the simplifying assumptions up-thread? E.g. no
indexes

On Thu, Feb 19, 2015 at 6:17 PM, Clayton Coleman [email protected]
wrote:

JavaScript. Anyone who has to do field validation or jquery or jq will be
able to leverage that format. The others are somewhat ivory tower

Reply to this email directly or view it on GitHub
#1459 (comment)
.

Sorry, I was responding to Sam, in that the format described by Eric works for me (no indexes) because it looks like what we would use for validation (which needs indexes), which we would probably end up using a lot in JavaScript (which benefits from the dot format).

----- Original Message -----

Is that still true with the simplifying assumptions up-thread? E.g. no
indexes

On Thu, Feb 19, 2015 at 6:17 PM, Clayton Coleman [email protected]
wrote:

JavaScript. Anyone who has to do field validation or jquery or jq will be
able to leverage that format. The others are somewhat ivory tower

Reply to this email directly or view it on GitHub
#1459 (comment)
.

---

Reply to this email directly or view it on GitHub:
#1459 (comment)

A version of this has been implemented in #40848 - clients can request only object metadata. Future enhancements will allow alternate schemas to be returned. The only consumer today is GC. Closing.

If anyone finds this and is wondering where some documentation is and/or what it's called: look up information on "Tables"

https://kubernetes.io/docs/reference/using-api/api-concepts/#receiving-resources-as-tables

tl;dr: add a header like Accept: application/json;as=Table;v=v1;g=meta.k8s.io