Open API Path Templating vs WHATWG URL Pattern

[AMorgaut]

The Open API Path templating seems to be inspired and partially compatible with the IETF [RFC6570] URI Template Specification which is great

Open API Path Templating

Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.

 Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item’s Operations. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.

The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986]: forward slashes (/), question marks (?), or hashes (#).

Examples

  /pets/{petId}
  /{entity}/me

But WHATWG recently announced its new URL Pattern specification

• https://blog.whatwg.org/url-pattern-standard
• https://urlpattern.spec.whatwg.org/

WHATWG URL Pattern Path Templating

A pattern string is a string that is written to match a set of target strings. A well formed pattern string conforms to a particular pattern syntax. This pattern syntax is directly based on the syntax used by the popular path-to-regexp JavaScript library.

It can be parsed to produce a part list which describes, in order, what must appear in a component string for the pattern string to match.

Example:

Pattern strings can contain capture groups, which by default match the shortest possible string, up to a component-specific separator (/ in the pathname, . in the hostname). For example, the pathname pattern /blog/:title will match /blog/hello-world but not /blog/2012/02.
A regular expression can also be used instead, so the pathname pattern /blog/:year(\\d+)/:month(\\d+) will match /blog/2012/02.

A group can also be made optional, or repeated, by using a modifier. For example, the pathname pattern /products/:id? will match both /products and /products/2 (but not /products/). In the pathname specifically, groups automatically require a leading /; to avoid this, the group can be explicitly deliminated, as in the pathname pattern /products/{:id}?.

A full wildcard * can also be used to match as much as possible, as in the pathname pattern /products/*.

https://urlpattern.spec.whatwg.org/#patterns

Impact

As you can see both pattern syntax is very different and not compatible

• Open API / URI Template: /foo/{bar}/baz
• WHATWG URL Pattern Path Templating: /foo/:bar/baz

There has been an issue pushed a while ago to this standard working repository

• Relationship with URI Templates (RFC 6570)
• Support for RFC 6570 (curly braces) path params

Actually it looks like this specification has been more driven by existing framework templating implentation (like express.js route parameters, Angular routing, ...) than by existing standards, while there also exists tools that had to be written to convert such product path template to the standard one (and vice-versa).

This feel pretty sad to me and I'm not sure what should be the best thing that could be done on Open API side:

• support both syntax ?
• provide a notice on how to translate one to the other ?
• do nothing and only rely on tools implementations ?

[handrews]

Actually it looks like this specification has been more driven by existing framework templating implementations

WHATWG's general mode of operation is to codify what implementations are actually doing. From what i can figure out of this URL Pattern spec, it's doing a somewhat different, although overlapping, thing from RFC 6570 URI Templates.

With Moonwalk (OAS 4) proposing full RFC 6570 support, the question is probably whether there are any use cases that are much better served by WHATWG's approach. I'm pretty certain that there are plenty of cases that 6570 enables that this new spec does not, but I can't entirely tell with just a quick look.

[handrews]

Can anyone summarize the grammar and capabilities of the WHATWG URL Pattern spec? As if it were a normal spec defined in terms of observable behavior instead of pseudocode for implementing a browser or analogous piece of software?

I am trying to figure out if it makes more sense to model after this than after RFC6570 but I confess I'm struggling to extract actual meaning out of the flood of implementation details.

[AMorgaut]

A more user friendly documentation is available on MDN

• https://developer.mozilla.org/en-US/docs/Web/API/URLPattern

With mention of 2 implementation libraries:

• https://github.com/pillarjs/path-to-regexp
• https://github.com/kenchris/urlpattern-polyfill

In browsers, It is currently supported by Chromium based ones (desktop 7 mobile versions of Chrome, Edge, and Opera) but not by Sarari or Firefox yet - it currently represent 74.83% of the users:

• https://caniuse.com/mdn-api_urlpattern

On server side, you will see it

• for express.js based services: https://expressjs.com/en/guide/routing.html#route-parameters
• Ruby on rail support similar path template: https://guides.rubyonrails.org/routing.html#connecting-urls-to-code
• used from python the de repath port of path-to-regexp: https://github.com/synacor/python-repath