Where to find the REST API for created Things?

[Martinocom]

Hello! I'm doing my best to understand all the stuff about Thing Description and WoT. I choose to test this framework over the "Mozilla" one, since ThingWeb has a native support for multiple context values (or at least, it does not overwrite them and I still can retrieve them when asking for the TD of my Thing).

Now, since my future project will require a raw REST API to use (and not a NodeJs / JavaScript based one), I was trying to find some references to where to find all possible operations I could make on a Thing. I don't want to use the API of this library, but the native REST protocol.

Some background. I have a simple bulb, with status (boolean: true/false) and a toggle action (self-explanatory).

With Postman I tried to make some blind requests, and I found that this combination works:

• GET http://localhost:8080/bulb/properties/status (no extra header/body)
  It returns just "false" or "true"

• PUT http://localhost:8080/bulb/properties/status (with header Content-Type: application/json and body set to "raw/JSON" true)
  It returns just the HTTP Status.

• POST http://localhost:8080/bulb/actions/toggle (no extra header/body, since it doesn't require any param).
  It returns just the HTTP Status, but I thing I could make it return anything I want.

• GET http://localhost:8080/bulb/all/properties (no extra header/body)
  It returns { "status": false }

So, are there some docs about all types of GET/PUT/POST/etc... combinations (or, at least, the most common and useful ones)?
And, is there any standard for passing/returning data? Like the just plain false or true values seems strange for me.

Thank you.

[relu91]

Now, since my future project will require a raw REST API to use (and not a NodeJs / JavaScript based one), I was trying to find some references to where to find all possible operations I could make on a Thing.

I am not quite sure about what you're asking, but if you're looking for a list of operation types allowed in a Thing Affordance you could look at the Thing Description document (precisely here see the op vocabulary term). Basically you can:

• read/write/observe a property
• invoke an action
• subscribe/unsubscribe to an event
• read/write multiple properties

[Martinocom]

Ok, I partially got it. It depends on "what" I'm trying to achieve with that particular op type. Clear.
But how I can know that op correspond to a _REST_CALL_ on something/to/call?

For example:

• it's clear that if I have a readproperty on a property, I'll expect to have a GET call on thing/properties/<property>/.
  But the fact I know this is only because I'm aware that REST works in this way, not because I know it from somewhere from docs.

• it's not so clear if i have a writeproperty: I could make a POST or PUT. And making those, where I must put parameters? In body or a param on URL?
  After making some experiments on Postman I figured out that writeproperty wants a PUT with a body set to application/json, and body must have the value that I want to set (like just true) or an object (like {"status": true}, and I must do it on the same URL as for the GET one (thing/properties/<property>/)

• it's even more not clear what can I do to subscribeevent: PUT or POST? With what kind of data (if any)?
  I expect like a PUT or POST on thing/events/<event>/ but with "what"?

• same thing for writeallproperties: must I pass a json with ALL my properties, only those ones that I want to change? Where I need to call it? A PUT or POST in thing/all/properties/?

Maybe I'm the one that didn't fully understand the Thing Description... Maybe it's the Thing Description itself that gives me this info, but I can't figure it out (some default values that I missed?). For this I'm asking a little help: maybe I'm not the only one that didn't find a reference to this.

[egekorkan]

So what is confusing is actually sadly not clearly documented. Depending on the protocol, different op values will map to different methods or "functions" of the protocol. For HTTP, it is as you have understood and it is "documented" here. The rest of the protocols are documented here. What is confusing you and that should be fixed in node-wot is that the default generated TD does not contain the default values and that is not documented nor there is a way to specify this, i.e. the Thing developer cannot say that these values should be present in the forms.

[Martinocom]

For HTTP, it is as you have understood and it is "documented" here. The rest of the protocols are documented here.

Awesome. I totally missed this part of the documentation. It clearly says what method uses which type of op.

And you're right, some parts are not well documented, but I think is also part of "our" job: we use it, we got what's good and we open an issue for things that are not good, right?

For the rest, I think I'm going to search most common (or draft-standard) patterns to use, just not to completly "reinvent the wheel".

Thank you.

[egekorkan]

No problem :)

For the rest, I think I'm going to search most common (or draft-standard) patterns to use, just not to completly "reinvent the wheel".

You don't have to use the default values btw, you can simply say how the request should be constructed and the WoT Consumers should understand it.

[danielpeintner]

What is confusing you and that should be fixed in node-wot is that the default generated TD does not contain the default values and that is not documented nor there is a way to specify this, i.e. the Thing developer cannot say that these values should be present in the forms.

@egekorkan I take your comment as an open issue we should look into. Right?

[egekorkan]

I think so. I'd say that there should be an option to generate TDs with default or not since there's no option to do it now. The default behaviour could be to generate the defaults since the beginners need more information.

[relu91]

I think is linked with #424, once we add canonicalization in practice the generated TD would have the default values. What do you think?