Return values for /property path

[balmas]

copied from RDACollectionsWG/rda_collections_api#4

@fbaumgardt says:
The spec describes a whole MemberItem as return value for a GET on properties. Is this desired? I could see this make sense on PUT or POST - receive the updated member - but for GET I would probably expect a single value (or object or array).

Thoughts?

@TobiasWeigel responds:
Yes, I agree that this is not consistent. Looking at the corresponding PUT I am also not sure whether the memberItem record even makes sense there. Wouldn't I just call PUT on one specific property, like ../properties/location? A PUT with the full MemberItem record would then only make sense for the root, /properties.

[balmas]

we are agreed to make this change.

[fbaumgardt]

Apparently we need to migrate to OpenAPI 3.0 for this. The response schema for single values from /property would need to specify all possible value types, and the current version (2.0) does not allow for multiple types per schema: OAI/OpenAPI-Specification#270. This is solved in 3.0

[fbaumgardt]

Added a draft for OpenAPI 3.0 here: https://github.com/RDACollectionsWG/apidocs/tree/OpenAPI3.0

[fbaumgardt]

While editing the specs files I was wondering about DELETE -- should we return the modified MemberItem, similar to PUT?

Edit: I should add that this isn't a recommendation, but really just a question. I'd like to think through the benefits of either solution.

[balmas]

Re DELETE return value. It could make sense. it could also make sense to return the # of items deleted, in thinking about future versions which might allow for multiple deletions to occur in a single operation. I guess one advantage of returning the deleted item might that it allows the client to rollback the deletion more easily if needed.

[balmas]

related to this -- perhaps Member POST should also return the Member Item rather than an empty response. If the Service supports ID minting for Member Items presumably the returned item would include the new ID. (I fear I'm opening a can of worms with this point though...)

[balmas]

According to the swagger 2.0 specification, leaving schema out of the response means that there is no return value. https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#responseObject

So per our discussion today, for the initial release of the API will leave this returning MemberItem and enter an issue for the future to upgrade to Open API 3.0 so that we can specify returning the property value with multiple types.

Separate issues will also be opened for the DELETE and POST discussions above.

[balmas]

Marking as enhancement and out of scope for initial release.

[fbaumgardt]

Thanks, Bridget! I like the idea to use issues and a label to gather postponed improvements upon v1 of the specs.

…

On May 9, 2017, at 12:36 PM, Bridget Almas ***@***.***> wrote: Marking as enhancement and out of scope for initial release. — You are receiving this because you were assigned. Reply to this email directly, view it on GitHub <#2 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAhw3x3lJvj4zIo4WT1mxv4OuURsA1vuks5r4JYmgaJpZM4NHgOd>.