Openapi specification only documents DELETE and PATCH for single entity URLs about odata-openapi HOT 6 CLOSED

Hi Ralf,

thanks for the fast and precise answer!
We are developing and using @balena/pinejs to auto-generate our OData API at balena.io. PineJs implements DELETE and Patch on filtered collections generically for every collection as it generates the end-points for each resource in the same way.

Thus, every instance of our open source published IoT fleet management tool https://github.com/balena-io/open-balena
and our balenaCloud API ( https://api.balena-cloud.com/ ) are supporting DELETE and PATCH on filtered collections.

The overall idea to use odata-openapi translator is to have it build into PineJS so that documentation renders, SDK generators and other tools can either use the OData CSDL or openapi spec to generate their outputs.
In particular the next goal are automatic updated openapi specs for documenetation, provided by PineJS directly.

I'll keep it on a watch and in the meantime I'll figure out how to add it to the openapi spec, I'm thinking of copy/pasta the block from the single entity documentation.

Thanks a lot again, best regards and have a good start into 2023

Harald

from odata-openapi.

Hi Harald,

Thanks for the info, and cool that you are building APIs with this feature.

I'll put support for FilterSegmentSupported into the backlog.

from odata-openapi.

Hi Harald,

Happy New Year!

PATCH and DELETE requests to filtered collections of entities aren't yet supported by the generator because I don't know of any OData services that support this advanced feature.

It could be added for services that advertise this feature via the FilterSegmentSupported property of UpdateRestrictions and DeleteRestrictions annotations.

I'll keep this issue open as a reminder.

If you know of services providing this feature, please tell me.

Thanks in advance
Ralf

from odata-openapi.

Hi Harald,

Could you please check whether https://petstore.swagger.io/?url=https://raw.githubusercontent.com/oasis-tcs/odata-openapi/a91398b3bbb24fb49054af7e275e6a673981a60c/examples/annotations.openapi3.json#/ matches your expectation?

The example shows /$filter(...) segments on a root entity set and on a collection-valued navigation property, each with DELETE and PATCH.

Thanks in advance

from odata-openapi.

Hi Ralf,

big thanks for the responsiveness and sending over an example to review!

The provided openapi spec looks exactly as the OData V4 core spec, so I think it's as expected.
We internally discussed it and unfortunately, our filtered collection actions for Delete and Patch follow the old V3 implementation:

DELETE /AllSet?$filter = {filter_expression}
PATCH /AllSet?$filter = {filter_expression}

How we will approach this now is:

• We will use these correctly documented V4 filtered collection endpoints and blatanty hack them to represent our old way :)
• Then we start with finding the gaps between our implementation, which is mostly V3 compatible, and OData V4 / V4.01.
• We aim for compatibility with OData V4.

One completely just curious question during our internal discussion was, why the filteredCollection PATCH and DELETE are ended with a $each. This feels redundant and from our understanding doesn't represent the otherwise full and unambiguous expressiveness of OData.

Thanks for your friendly and open support!

Harald

from odata-openapi.

Hi Harald,

Assume we have a bound function foo with two overloads, one bound to a single thingy, and one bound to a collection of thingies.

This leads to the following request patterns

The request with the URL ending in /$each is kind of an iterator over the filtered collection and allows us to decide which overload to call.

We have the same ambiguity with PATCH because we allow update requests to collections now, sending a delta payload as the request body.

And we use the same pattern for DELETE requests although we haven't yet specified a meaning for DELETE /thingies.

The function call example also shows why we added the filter in the path. If the collection-bound overload returns a collection, there are two collections to filter: the input and the output of the function.

Having the filter query option always filter the output of an operation simplifies things.

Hope this explains how we arrived at the current URL syntax.

Ralf

from odata-openapi.