Full-URI parameters


Short said: in my scenario I would like to have a raml-specification, which contains full-uri parameters.

But I think an example is more effective than my words.
Having this simplified raml description:

baseUri: http://example.org/next



And the reponse for http://example.org/next/item/againitem/values would be some JSON like

So coming from my view (the person who writes the specification), I know that the item parameter is {item} = /item/againitem
But looking at the JSON response the correct item path is http://example.org/next/item/againitem
In my Linked Data application the paths are always notated that way.

Coming from user’s view my RAML-Spec would be misleading, because it says
I would “look up the item name/path” and fill it at the place of {item}.
This leads to http://example.org/next/http://example.org/next/item/againitem which is obviously wrong.

Is there a workaround for that or am I thinking too complicated and got it twisted?
The JSON response should stay the same, I simply would like to describe the current state of that REST-API with RAML.

I was thinking about leaving the baseURI empty, but then the slash before {item} would be wrong and raml2html renders this slash in the html-file.

Thanks for reading


So you want to use RAML to describe a hypermedia API (REST) with links right? That means you have a base URI from where a consumer can use the JSON response, and most likely links in it, to navigate your API.

Sorry, I’d want to clarify your intention before answering your question.


I’m not really sure, but I would say it’s not hypermedia, as these item URIs are not really links in URL sense.

They uniquely identify some machine, which has different property values (time/value pairs).
My main problem is that the above RAML Spec suggests that the machine-URI is only the part between next/ and /values. But in reality it’s including the base-URI (first in JSON response).

looking at the RAML-Spec I can go to
http://example.org/next/item/againitem/values and get values for the machine
which URI is the part between next and values = item/againitem != machine-URI
as machine-URI is http://example.org/next/item/againitem

I hope this clarifies my point a bit more!?
Like I wrote in the second part I think that the RAML Spec is not correctly describing the real API, but I dont know how to do it any better.


You are right; RAML does not describe the behaviour but rather the interface.


This means there’s no workaround to describe this scenario properly?


You can certainly describe it using JSON Schema, e.g. a Links/Link schemas, and in your other schemas, refer to the Links/Link schemas as necessary so that each URL response can optionally return the links.