Support for semantic path templating

[trilean]

Hi,

I recently ran into the following issue: I have two different types of URIs which support different requests (verbs) and return different values. I tried to write them down as:

paths:
  /{CollectionURI}:
    get:
      summary: List Collection Members
      ...
    post:
      summary: Create a Resource
      ...
    parameters:
      - $ref: "#/parameters/CollectionURI"
  /{MemberURI}:
    get:
      summary: Retrieve a Resource
      ...
    parameters:
      - $ref: "#/parameters/MemberURI"

...which does show up fine in Swagger-UI but is not officially supported. Swagger-Editor doesn't like it and shows an error.

I asked that question on SO: https://stackoverflow.com/questions/35478531/swagger-equivalent-path-already-exists-despite-different-parameters

Please add support for this kind of path templating in the next version.

Thanks!

[webron]

Can you share more details on the actual parameters? As @fehguy mentioned on SO they are identical path-wise, and without the details on the parameters it's unclear how you differentiate them. It could be different type for the path parameter, but it could be that you depend on other parameters.

[trilean]

For example a POST to a ${CollectionURI} returns 201, a Location Header to the newly created ${MemberURI} and its body. There is no POST to a ${MemberURI}, only PUT and DELETE (which are not available on a ${CollectionURI}).

I don't have the code with me ATM, I'll post it later.

[webron]

But both of them have a GET operation - how do you tell them apart?

[trilean]

Here is the code. I removed the descriptions to make it a bit shorter.

paths:
  /{CollectionURI}:
    get:
      summary: List Collection Member
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/AtomFeedDocument"
    post:
      summary: Create a Resource
      responses:
        201:
          description: Created
          schema:
            $ref: "#/definitions/MemberRepresentation"
          headers:
            Location:
              type: string
              format: URI
      parameters:
        - $ref: "#/parameters/MemberRepresentation"
    parameters:
      - $ref: "#/parameters/CollectionURI"
  /{MemberURI}:
    get:
      summary: Retrieve a Resource
      responses:
        200:
          description: OK
          schema:
            $ref: "#/definitions/MemberRepresentation"
    put:
      summary: Edit a Resource
      responses:
        200:
          description: OK
    delete:
      summary: Delete a Resource
      responses:
        200:
          description: OK
    parameters:
      - $ref: "#/parameters/MemberURI"

But both of them have a GET operation - how do you tell them apart?

I want to view a request to /path/to/id as something like edge --> edge --> node (or branch --> branch --> leaf). If the last part of the URI is a node (i.e. a Member in Atom's case) it's a MemberURI, else a CollectionURI.
The problem of course is that you can't know that from in advance.

From @fehguy 's answer on SO I figure this is not (easily?) doable?

[whitlockjc]

Unfortunately, this doesn't explain how to differentiate the two "different" paths that are semantically the same. (They are semantically the same because they describe a path with a single path segment that itself is a variable.) There has to be something in the path definition that makes that definition unique and your two path definitions do not do that. If you run that through swagger-tools validate, it would tell you that this is invalid Swagger. Not only that but it seems like you're trying to have a variable for one path segment but what you really want (I'm guessing here...) is a wildcard because you're not defining one path segment that is a variable but potentially N path segments as a variable. I'm not sure Swagger supports that, in fact I had to work around this in swagger-tools using a vendor extension. (I'd love to be wrong on this one and learn something.)

So without something concrete in your path definition, it will be impossible for any smart validator to differentiate between the path patterns because the are semantically the same. (Feel free to npm install -g swagger-tools && swagger-tools validate YOUR_FILE to see the results.) Why not change it so your paths were /collections/{URI} and /members/{URI}?

[webron]

So you have an API with a a URI that is identical for two different operations (all the parameter definitions are identical as well including header, path and query parameters), and based on the path parameter the client will get one of two results but the client has no real way of knowing that when calling the API?

[fehguy]

Unfortunately this is supported in different server frameworks by routing the request based on regexes on the path parameters. I am not saying we should support it but it is somewhat common.

Declaring the regex in the path parameter in the path makes this more tolerable but you still have to deal with the order of the routing, etc

[whitlockjc]

I know there is regex support in routers and such but the blanket "This API matches anything after the slash" just isn't very beneficial. And while you could assume that this is backed by some regex matching router, which could very well be the case since that is a common feature in routers, even then there is a chance that there is more of a pattern that could be put into the path definition than what is there now.

[webron]

But @trilean never mentioned that the path parameter is differentiated by a regex. Who says a given 'name' can't be used for both a member and a collection? He could just be checking it in the BE, checking out one and falling back to the other if it doesn't exist.

[whitlockjc]

That's why I said "while you could assume this is backed by some regex". ;) But yes, you're right that this could a the case where the only one differentiating this is on the backend.

[webron]

But I was replying to @fehguy. Not everything is about you, @whitlockjc.

[whitlockjc]

Blame the async responses @webron, not my theorized ego.

[theganyo]

Mommy and daddy are fighting again.

[whitlockjc]

👍

[trilean]

Thank you for your answers! Sorry for not having been more specific on this. It seems we're talking about two somewhat seperate issues here:

1. The return types (schemae) for a request to a MemberURI and CollectionURI are not the same. CollectionURIs always yield an Atom Feed Document while a Member may be an image, an XML document or anything in between. Which is why I want to differentiate the two. Usually it'll be an Atom or XHTML document (depending in the accept header).
2. I have not implemented anything so far because I tried to do a proper specification first 😉 In my head it goes something like this: I want to store my documents in a tree. The (URI) path segments correspond to the branches in the tree. If the path doesn't point to a leaf (i.e. single document), the data store returns a list of all leafs below the branch specified in the URI, hence a collection. E.g. if you GET / you'll get all documents.

Actually I want to use a graph but it's easier to imagine with trees.

Also, there is no fixed number of path segments (depth of the tree). Can wildcards handle this?

Why not change it so your paths were /collections/{URI} and /members/{URI}?

To me that feels like a workaround. It's 2016 and I really really want my URIs to represent my data and not some implementation details / issues.

But yes, you're right that this could a the case where the only one differentiating this is on the backend.

Exactly.