Slash characters in URI parameters


#1

I’ve just starting to investigate RAML as a way to document our APIs and I hit a snag with the spec:

The values matched by URI parameters cannot contain slash (/) characters, in order to avoid ambiguous matching.

We have RESTful APIs in use that describe a hierarchy of resources. We like to express the hierarchy naturally in the URI using a path as a parameter. For example, an RFC 6570 template for my resource would be /resources{+path} and the resources /resources/foo, /resources/foo/bar, and /resource/foo/bar/baz would all map to it with path parameter values of /foo, /foo/bar, and /foo/bar/baz, respectively.

Obviously the API design must be careful to avoid URI ambiguity, but I see no reason for RAML to prevent the description of such an API. Thoughts?


#2

You are right. I think that RAML should not have this restriction.

I do however agree with the comment in the RAML spec, in the sense that removing this restriction open the door to ambiguous APIs.
Also, It is quite clear to me that automated server/routing generators are going to have issues in providing uriParameters parsing if we allow slashes in uri parameters.

I.E.
/resource/{param1}/another-resource/{another-param}

If param1 can contain slashes, only a very custom parser can assure correct parsing of this URL.

Should the spec state that uri parameters MAY contain slashes only on the last uri segment?
Or should it be left wide open, and let server side stub | routing generators say that they cannot handle slashes on those uri parameters?


#3

Personally, I am fine with having the restriction that only the final parameter may contain slashes. Also, I suggest adopting the RFC 6570 notation for reserved expansion to indicate the possibility of slash characters occurring. This makes it explicit that certain params can contain slashes. It’s entirely possible that an API may expect a slash to be percent-encoded.

This would be invalid:

/resource/{+param1}/another-resource/{+another-param}

But this is acceptable:

/resource/{param1}/another-resource/{another-param}

As is this:

/resource/{param1}/another-resource/{+another-param}

With the latter of the two acceptable URIs allowing slashes in the value of another-param.


#4

I like the idea of allowing the last parameter to contain slashes but only if it is explicit. The Camel Jetty component uses this concept where everything after the defined path can be included as a parameter, but only when enabled.

So the following would allow /'s:

/resource/{param1}/another-resource/{+another-param}

If not specified then it fails:

/resource/{param1}/another-resource/{another-param}

This avoids ambiguity where at some later point the designer gets crazy with:

/resource/{param1}/another-resource/{another-param}/yap/{yap}