Full-URI parameters


#1

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

[...]

/{item}:
 /values:
  [...]

And the reponse for http://example.org/next/item/againitem/values would be some JSON like
{“http://example.org/next/item/againitem”:
{“http://example.org/next/item/againitem/property”:[
{“time”:1476858688950,“value”:44432.8454},
{“time”:1476858687854,“value”:44324.2923}}]}

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
http://example.org/next/{item}
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


#2

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.


#3

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).

f.e.:
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.


#4

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


#5

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


#6

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.