New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Optional "minimal" response? #21

Closed
switzersc opened this Issue May 21, 2017 · 8 comments

Comments

Projects
None yet
4 participants
@switzersc

switzersc commented May 21, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 23, 2017

Contributor

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.

Contributor

kinlane commented May 23, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 24, 2017

Contributor

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.

Contributor

kinlane commented May 24, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane May 30, 2017

Contributor

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

Contributor

kinlane commented May 30, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Jun 2, 2017

Contributor

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.

Contributor

kinlane commented Jun 2, 2017

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

This comment has been minimized.

Show comment
Hide comment
@klambacher

klambacher Jul 13, 2017

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.

klambacher commented Jul 13, 2017

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

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Jul 14, 2017

Contributor

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.

Contributor

kinlane commented Jul 14, 2017

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.

@NeilMcKechnie

This comment has been minimized.

Show comment
Hide comment
@NeilMcKechnie

NeilMcKechnie Aug 10, 2017

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

NeilMcKechnie commented Aug 10, 2017

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

@kinlane

This comment has been minimized.

Show comment
Hide comment
@kinlane

kinlane Aug 31, 2017

Contributor

Closing and running with #45 /complete.

Contributor

kinlane commented Aug 31, 2017

Closing and running with #45 /complete.

@kinlane kinlane closed this Aug 31, 2017

@NeilMcKechnie NeilMcKechnie referenced this issue Sep 4, 2018

Open

/search #46

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment