search

openreferral / api-specification

This is the working repository for Open Referral's Human Services Data API protocols.
https://openreferral.readthedocs.io/en/latest/hsda/
Other
29 stars 13 forks source link

Optional "minimal" response? #21

Closed switzersc closed 7 years ago

switzersc commented 7 years ago

The location response is quite big, and on one hand this is awesome, because it ensures the client by default gets the info it needs. However, it’s quite a hefty payload and any mobile clients would prefer something smaller. What about having an option to request this resource with a minimum response (e.g. just the location resource, excluding organization, categories, etc) so that clients concerned about package size can opt for something smaller?

See Irakli's post about one possible approach to this: http://www.freshblurbs.com/blog/2015/06/25/api-representations-prefer.html

kinlane commented 7 years ago

Agreed. Love that you are bust'n out Irakli advice!! Following...and baking into how we keep an eye on all of our resources -- keep em small and useful.

kinlane commented 7 years ago

So I really like the concept of using HTTP Prefer Header to allow for "minimal" (vs "standard" or "full"). I see the schema having just shed it's CSV cocoon. I would equate the current schema used in the API to be flat, very CSV one dimensional, or minimal. I would like to thoughtfully craft a standard and / or full definition as I push forward the surface area of the schema in context of the API definition. Thank you for this suggestions. I love learning about sensible approaches like this, from people I respect.

kinlane commented 7 years ago

Some questions to ask that came in on via a blog post I did on this from Chris Snyder:

  1. How would this be documented in OpenAPI/Swagger?
  2. Will caching HTTP proxies properly respect this header? (edit: the linked article answers this: make sure to specify "Vary: Prefer" in the response)

Source: http://apievangelist.com/2017/05/24/considering-http-prefer-header-instead-of-field-filtering-for-my-api/#comment-3323980380

kinlane commented 7 years ago

I struggled with this issue as part of the v1.1 release. The 1.0 of the Ohana implementation gives a fairly full if the inconsistent view of locations that includes phone, address, and other sub collections.

Ideally I wouldn't make a breaking change from v1.0 to v1.1, but since v1.0 technically wasn't an API specification, it was just extracted from the Ohana implementation--I'm going to.

For v1.1 I'm going to keep locations/, organizations/ and services/ paths a simple representation of the schema, without expanding any subcollections. I feel like release should offer a simple representation of each entity as the default. In v1.2 I'd like to add schema filtering, allow users to ask for one, or many versions of an expanding and fuller version of the schema.

I feel like we should always default to simple, and allow for consumers to ask for complexity. Not the other way around.

I will be putting deep thought and encourage discussion around how we implement schema filtering for GET, POST, and PUT requests, allowing the reading and writing of simple or complex collections.

klambacher commented 7 years ago

We have what is (maybe?) a weird approach with our current API in that each API account has the capacity to have customization on the fields return for bulk record lists (i.e. search results) and full record displays (i.e. record details). This is a heavily used feature, so I am biased towards the need to have control in this area. We have not found much consistency in what data clients want for display, particularly in bulk record lists.

We do have a simple simplified API for public use that doesn't require a full API account (therefore doesn't have this customization tied to the account), and for that one we allow customization through the use of a default set of fields and the option to send in a comma-delimited field list with the request indicating you only want those fields returned. This increases the message size which is not great, but does offer a lot of control in return. I think the problem with the concept of "simple" vs "full" is that in the real world with many data clients, they will not agree on what the essential fields are so this is extremely difficult to standardize.

kinlane commented 7 years ago

Thanks for the feedback. It definitely reflects the spectrum we want to cover with v1.2 release--good to hear.

v1.1 reflects exactly the schema - simple organization. v1.2 we'll add complete representation. organization plus sub-resources. v1.2 we'll add a parameter for selecting everything in between.

Should cover the spectrum of needs, keeping the basic schema as default.

Would love to talk more about the "customization tied to the account" sometime too as side conversation.

NeilMcKLogic commented 7 years ago

@kinlane is this getting implemented now? I'm going through these issues chronologically so maybe in a later thread.

kinlane commented 7 years ago

Closing and running with #45 /complete.