Use URI-templates

[grncdr]

From the spec:

XXX How can non-placeholder :foo's be included in the path? i.e. is there an escape mechanism? XXX What happens in this example if 'format' isn't listed in params/required? XXX What happens if a parameter needs to be followed by a word character? i.e. can something like :{format}foo be used?

I would suggest using http://tools.ietf.org/html/rfc6570 URI-templates rather than the template format you use now. If you don't want to mandate a fully compliant implementation as part of SPORE, then "level 1" templates are extremely simple, (basically you replace :foo with {foo})

Tangentially, I'd appreciate your input over on https://github.com/anodejs/node-docrouter/issues/1, it seems as though we all may be re-inventing the same wheels.

[almet]

+1 for this specification over the :identifier one. I'm glad this issue was opened to discuss this. Did you got any feedback on this so far?

[ngrunwald]

Actually, these are just notes about the questions we had when writing the spec, that somehow were not removed afterward. : is a reserved character in URLs, it is quite unlikely to appear in the path of an API method. Hence, no escaping mechanism needed in practice if not in theory. If a param is not listed as required and not given by the client call, then the : remains in the URL. As the name of the parameter is known, there is no need for a delimiter to have it followed by a word.

"/:filename.txt" called with $filename => "foo" becomes /foo.txt

In truth, we didn't know about URI-templates when we wrote the spore specifications. We choose to go with the : syntax because it was already widely used server-side (by Rails, Dancer, Compojure and surely countless others...) and so already familiar to most. I would honestly be extremely wary at this point to break compatibility with all our implementations. Have you real world examples of public APIs where our current scheme cannot be made to work? Anyhow, there should be answers and not only questions in this paragraph, I'll update it with this!

About docrouter, we are indeed working on the wheel, but not for the same vehicle I guess. Specifically, SPORE was designed not to go the WADL route, as we found the spec to be too verbose and cumbersome to read and to write. As such, SPORE does minimum param validation (and nothing about those in BODY, though we are thinking about that), and does not specify anything except status code about the response. A SPORE spec can be written in 5 minutes while reading the documentation of an API or writing the routes of the server, which is exactly what we wanted. On the other hand, with our middleware system, we propose pluggable ways to reuse code for things like caching, authentication, logging, mocking... Our goal seems more lightweight than the problem you set out to solve. But, if you want, I'd be happy to compare notes, for exemple in our mailing list here: http://groups.google.com/group/spore-rest

[fperrad]

We cannot break compatibility with existing code. But we could support both schemes : :foo and {foo}

I try it in a branch of lua-Spore see https://github.com/fperrad/lua-Spore/commit/b3dbd35b977912994ac42c4d7030010bd0961444