Change path structure

[cportele]

During discussions at the WFS 3.0 hackathon the following new path structure was discussed by a subgroup and was supported by the participants (underlined paths are part of the core, all other in extensions):

Advantages:

• avoids naming collisions
• clearer hooks for extensions
• more compatible with some/many URI routers
• can support servers with many collections (paging of collection metadata may be specified in an extension)

[aaime]

Would it be possible to allow implementation to use a more freeform path, like in the case of GeoServer setups, /collections/topp/states for example? Right now I'm mapping it to /topp__states to avoid having a ":" in the path, but it's ugly and potentially error prone.
The location of where each collection is could be provided in the contents document.

[pvretano]

Andrea's comment makes me think that should let the server define the path to each collection via hypermedia control (as was done with WFS 2.X in the capabilities document). So, the landing page will have all the usual links, /api, /conformance, etc. BUT there will be no /collections path. Instead, the landing page will contain hypermedia controls with "rel=collection" with the link(s) to each collection. Resolving that link will, as it does now, get you the metadata about the collection.
I have partially implemented this in my server to illustrate the point: http://www.pvretano.com/cubewerx/cubeserv/default/wfs/3.0.0/foundation?f=json
I have intentionally replaced the "collections" path element with "pathElement01/pathElement02" to emphasize the fact that the server can choose its own path to each collection. These links will not "actually" work right now since I only did a mockup in my server. Extending this idea further, similar hypermedia controls would be used to get to the features themselves, to get to the schema of the collection, to get to a map, etc. In other words navigation is hypermedia driven rather than by predefined paths. Too radical? Not sure if this breaks tools like swagger or not.

[lieberjosh]

Peter, There has been this idea that “purer REST” should be independent of any URL structure. It sounds as if flexibility of choosing URL’s is a good thing, but it does comes at a cost and due to a misconception. The misconception is that URL paths somehow must reflect a file structure or other internal operation of a server. With re-writing, re-direction and other modern server capabilities, this does not need to be true. The cost is that any semantic content of the URL is then lost, hidden away in the details of the hypermedia controls. This is fine when the server is supplying the application as well as the service, but it isn’t really consistent with independence of services from applications. If collection paths are omitted, then in order to provide something predictable that app developers can rely on, I suspect that WFS implementations will just end up with a consistent informal URL structure that isn’t maintained in the specification. It certainly can coexist with rel links in either hypermedia or headers (or both). One possibility, I suppose, would be to make defined /collections paths another extension, in case there is another good argument for not specifying canonical collection URL’s —Josh

…

On Mar 18, 2018, at 6:07 PM, Panagiotis (Peter) A. Vretanos ***@***.***> wrote: Andrea's comment makes me think that should let the server define the path to each collection via hypermedia control (as was done with WFS 2.X in the capabilities document). So, the landing page will have all the usual links, /api, /conformance, etc. BUT there will be no /collections path. Instead, the landing page will contain hypermedia controls with "rel=collection" with the link(s) to each collection. Resolving that link will, as it does now, get you the metadata about the collection. I have partially implemented this in my server to illustrate the point: http://www.pvretano.com/cubewerx/cubeserv/default/wfs/3.0.0/foundation?f=json <http://www.pvretano.com/cubewerx/cubeserv/default/wfs/3.0.0/foundation?f=json> I have intentionally replaced the "collections" path element with "pathElement01/pathElement02" to emphasize the fact that the server can choose its own path to each collection. These links will not "actually" work right now since I only did a mockup in my server. Extending this idea further, similar hypermedia controls would be used to get to the features themselves, to get to the schema of the collection, to get to a map, etc. In other words navigation is hypermedia driven rather than by predefined paths. Too radical? Not sure if this breaks tools like swagger or not. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#64 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AExWhulzmC80I8589p6eDwdiOtoenjPEks5tftqVgaJpZM4Sfl7b>.

[cholmes]

I think I'm -1 on just letting the server define the path to collection. My thinking is mostly in line with Josh's. I think there's a value to the semantic content of a /collections to communicate simply in the URL that this is in fact a collection. To make a pattern that is easy for any one to identify. I know that if I go to /collections/ I'll get a list of all the collections. If I go to /items then I know I'll get the items.

That said it'd be good to meet Andrea's use case, as it is a common one. And indeed also to address servers that have tens of thousands of collections, which I think we may just need some paging on that item.

It seems to me that it would be ok to just give the flexibility under the 'collections' to organize the URL more flexibly? And I think it'd make sense for /topp/ to return the list of collections underneath it - like have it be a real resources that can be queried.

[rcoup]

@cholmes so you're suggesting supporting collections having a name property containing slashes (as a namespace/theme selector)?

ie.

• name=topp/states -> /collections/topp/states/items
• name=buildings -> /collections/buildings/items

[rcoup]

And I guess /collections/topp could have the same result request/response syntax as /collections but only for topp/* named collections

[jvanulde]

I am on the fence with this idea of prescribing a path to "collections". Few people even understand the concept. In the real world, people will use things such as "buildings/building-1" or "outcrops/canada/ab/lethbridge/outcrop-1" etc. I understand the practical and pragmatic reasons for prescribing it in core but I would do so with caution as it is an anti-pattern from the purists' viewpoint.