Allow recursive paths

[dstovall]

I'd like to create a recursive path specification.

I'll give an example: Imaging a system to serve documents with lots of decomposition (e.g. laws, codes). Documents are organized in a tree-like structure of sections. Each document has an arbitrary number of authors and/or sections. Each section has an arbitrary number of it's own authors and/or sections.

The API endpoints would be something like this:

• http://a.b.com/docs/{id}
• http://a.b.com/docs/{id}/authors/{id}
• http://a.b.com/docs/{id}/sections/{id}
• http://a.b.com/docs/{id}/sections/{id}/authors/{id}
• http://a.b.com/docs/{id}/sections/{id}/sections/{id}
• http://a.b.com/docs/{id}/sections/{id}/sections/{id}/authors/{id}
• http://a.b.com/docs/{id}/sections/{id}/sections/{id}/sections/{id}

If I were using regex style, I would use something like this in the API spec:

( /path )+

So the spec would look like this:

...    
paths:
    /docs/{document-id}:
          ...
    /docs/{document-id}(/section/{section-id})+:
          ...
    /docs/{document-id}(/section/{section-id})+/authors/{author-id}:
          ...

This is similar to https://github.com/OAI/OpenAPI-Specification/issues/892 ; but these paths are not arbitrary, they are structured and deterministically matchable.

[handrews]

@dstovall I've yet to see a system that handles this well. Even with full URI Template support, indefinitely long alternating path components are a challenge. You can get arbitrary repeating path components, driven by array elements, but that's not quite the same.

[dstovall]

@handrews Would it be simpler if I didn't need a server stub for these endpoints?

My primary need is to generate clean, consistent documentation of the API. Ideally, I would also generate client stubs. If I could get those two things, I'd be more than happy to route the request myself based on the request's path components.

[handrews]

@dstovall I was really just thinking about URI Templates and the client-side of things. I honestly hadn't even thought about the routing issues. I'm not an OpenAPI expert in any event, so take my comments with a grain of salt. I'm coming at this from my experience trying to get a similar example to work while writing the forthcoming JSON Hyper-Schema draft (which addresses a slightly different problem than OpenAPI anyway).

I could not figure out any way to make it work with RFC 6570 URI Templates, and if anyone else has figured that out I would love to hear about it.

[darrelmiller]

With URI Templates you would do this: /docs/{document-id}/section{/section-id}/authors/{author-id}

But that would make the URI /docs/99/section/2/7/1/authors/78

OpenAPI currently doesn't support describing paths using that format.

[handrews]

Each document has an arbitrary number of authors and/or sections.

@darrelmiller this is the part that I think can't be done with URI Templates. You can support any fixed level of nesting, and if you just want to expand an array into path components you can do that, but you can't do alternating names and ids (unless your array is alternating names and ids which, I suppose, you could do, but that's pretty gross).

[handrews]

This level 4 URI Template:

{/data*}

applied to:

{
    "data": ["docs", 1, "sections", 2, "sections", 3, "authors", 4]
}

would produce: /docs/1/sections/2/sections/3/authors/4

(but... ick)

[cmheazel]

Let's try another use case --- A Feature is a representation of a real-world object (ISO 19107). It contains a location, geometry, and attributes. So a Feature can represent a window, door, wall, etc.

Now a Feature can also be a collection of Features.
A house is a collection of windows, doors, walls, etc. A town is a collection of house Features. A county is a collection that includes town Features. And so-on ad-infinitum.

One would be tempted to build an API based on the tree of collections /{collection}/{collection}/.../{feature}. To do this, we need recursive paths. My sense is that this would quickly become unmanageable.

Another option is to organize the Features into a graph. You get to any Feature using /Features/{feature_id}. Each Feature includes links to its' adjacent Features on the tree. The client can navigate to any Feature by following the links. In this case, we don't need recursive paths. But we may need to support JSON-LD.

Comments?

[handrews]

@earth2marsh @darrelmiller I think this issue should probably be moved to a Moonwalk discussion since that's where we're looking at full RFC 6570 support - I don't have permissions for that, so could one of you transfer it please?