Schema Filter Parameter (fields=)

[kinlane]

Adding a parameter for filtering the schema.

Providing comma separated list of fields, and sub-resources.

Suggesting we call it fields=

[boxfoot]

I think there are actually two questions here. The same syntax might handle both, but worth calling them out:

1. Which fields to include on the requested resource -- e.g. when I GET /organizations/12344, which (scalar) fields are populated on the returned resource? Similarly with collections, when I GET /organizations?zip=55104, what fields are populated on each of those resources?
2. Which subresources should be included? E.g. when I GET /organizations/12344 does it also include all of the related services, or just the organization itself? Note that:
   • This applies not only to child resources (services attached to an organization) but also to parents (requesting GET /services/12332, does it return the organization object as well?)
   • Applies regardless of whether we're doing a deep-nested JSON structure or using hypermedia to include the children
   • Has a nesting challenge -- if we're including services with organizations, do we also include their eligibility and documents? -- if we're including programs with organizations, do we also include their services (and eligibility and documents)?
3. Question (1) also applies to question (2) -- when we provide subresources, need a way of thinking about which fields are populated on those subresources (and sub-subresources, etc.)

@kinlane it would be awesome if you could share out any models of how other highly-scaled APIs are handling this question w/ specifics...

[tuckerbuchy]

Took at least a stab at this: https://github.com/openreferral/api-specification/pull/57

[kinlane]

You rock @tuckerbuchy -- The suggestion is solid, and will include in strategy guidance. Your approach to recommending for the road map solid too. Refreshing.

[tuckerbuchy]

@kinlane Thanks! Really liking the OpenReferral project thus far. Hope to keep in the loop with things!

[NeilMcKLogic]

Excellent questions @boxfoot . @kinlane where are we landing on this?

[kinlane]

This issues span schema and data filtering. In v1.2 the only schema filtering will be HSDS (simple) or /complete. With more usage data I will consider a solution in future versions for everything in between.

Regarding data filtering (ie. which fields to search for which values), I will be accepting @tuckerbuchy pull request #57 making query into array, as it is simple, concise, and reflects wider standards.

Once challenge. How do you specific core resource fields, as well as sub resources fields. I will be making more recommendations on this after I play with in prototype. Ideally, the entire field surface area is represented.

[kinlane]

To allow for schema filtering I am adding two properties:

      - in: query
        name: fields
        description: A list of fields to be returned with the response, if not included,
          all are returned.
        schema:
          type: string
      - in: query
        name: resources
        description: A list of resources to be returned with the response, if not
          included, none are returned
        schema:
          type: string

This will allow for the user to choose which fields they want in the response, as well as what resources.

If fields is left empty it will return all fields. If resources is left empty it will return no sub-resources. You will not be able to filter fields on sub-resources.