I’ve been playing with uri-templates a little bit at $work to help formulate clean urls for a newspaper application. The goal is to provide urls such as:

  • http://example.gov/issn/0362-4331
  • http://example.gov/issn/0362-4331/1969-05-28
  • http://example.gov/issn/0362-4331/1969-05-28/1
  • http://example.gov/issn/0362-4331/1969-05-28/1/31

I was hoping something like this would work:

  • http://example.gov/issn/{issn}/{date}/{edition}/{page}

But I’d like to indicate that the date, edition and page parameters are optional. After reading the spec and some discussion it becomes clear that there is no way to indicate that part of the path is optional. OpenSearch addresses the issue to some extent by making parameters optional with ‘?’:

  • http://example.gov/issn/{issn}/{date?}/{edition?}/{page?}

Which seems to be what I want. But there are some wrinkles such as when a page is included without a date. But perhaps these details could be application specific?

The discussion seemed to indicate that the template could be bundled with a written description of how the parameters are to be used. Or instead an additional template specification for optionality could be created which references the URI Template spec. There were also some nods towards WADL, which apparently has some richer conventions for this sort of thing.

I guess for the moment using

  • http://example.gov/issn/{issn}/{date}/{edition}/{page}

with some descriptive text will work good enough. But I think it would be useful if the uri-template draft commented on the issue somehow…since it’s bound to come up again.