Leshan server REST API

[onovo1]

Question

Hi,

is there any documentation of the REST API supported by the Leshan server? I couldn't find anything and going through the code to figure out the options is a bit painful.

I found this link but it is not updated and/or well documented with proper examples:

http://robertsrhapsody.blogspot.com/2018/01/eclipse-leshan-rest-apis.html

Thanks!

[sbernard31]

is there any documentation of the REST API supported by the Leshan server

This is REST API of leshan-server-demo. This API is not intended to be reused, so of course there is no documentation.

You can get look at :

• https://github.com/eclipse-leshan/leshan/wiki/F.A.Q.#could-i-reuse-leshan--demo-
• https://github.com/eclipse-leshan/leshan/wiki/F.A.Q.#is-there-a-rest-api-for-leshan-server-demo-

[onovo1]

Thank you for your message!

I'm aware that the REST API in the demo Leshan server is not intended for commercial use. In our case, we are utilizing it solely as a testing tool.

Our goal is to create new resources in the Leshan server using the REST API, but we have encountered challenges in accomplishing this task.

Our existing code is outlined below:

  type: "POST",
  url: "https://leshan.eclipseprojects.io/api/clients/IO_client/",
  payload: {"id": 1, "object": 26241, "resources": [{"kind": "singleResource", "id": 5601, "type": "FLOAT", "value": "13.1"}]}

Thanks!

[sbernard31]

I'm aware that the REST API in the demo Leshan server is not intended for commercial use. In our case, we are utilizing it solely as a testing tool.

Yep it seems there is a lot of people who do that. 🤔
That sounds like a common need, so maybe one day we should try to provide a real solution about that but currently there is very few people who are regularly involved in the project and so not enough manpower to enlarge the project scope.

Could you described a bit more how you are using it ?

Our goal is to create new resources in the Leshan server using the REST API, but we have encountered challenges in accomplishing this task.

Did you try the tips about :

• launching your web browser with developer tools
• use web UI for feature you want to access with REST API
• see how looks like HTTP request / response

?

Maybe a missing media-type ?

[onovo1]

Could you described a bit more how you are using it ?

We have a REST client to perform automated queries, updates, and deletions of resources in the demo Leshan server. While we've successfully managed to update and delete resources, we've encountered an issue in creating new resources, and we can't figure out what is the reason for that.

Did you try the tips about :

launching your web browser with developer tools
use web UI for feature you want to access with REST API
see how looks like HTTP request / response

we did, using the web UI works. However, it doesn't align with our primary use case. Our objective is to automate the process through our client REST API. The web UI requires manual interaction, and it is notably slower.

Maybe a missing media-type ?

It is possible, but we haven't managed to figure out what is the problem and the error message we received from the Leshan server lacks clarity in describing the problem.

[sbernard31]

we did, using the web UI works. However, it doesn't align with our primary use case. Our objective is to automate the process through our client REST API. The web UI requires manual interaction, and it is notably slower.

The idea is to use Web UI + web browser dev tools to explore the REST API and then you know how to use it in your code.

the error message we received from the Leshan server lacks clarity in describing the problem.

Share the error message + share a curl command which reproduce the issue.
And I could try to help.

[onovo1]

The idea is to use Web UI + web browser dev tools to explore the REST API and then you know how to use it in your code.

Yes, you are absolutely right and this is how we have done it so far but the Web UI does not give the option of creating new resources, right? only new instances.

So, when we try to enable a new object using the REST API, for example:

  type: "POST",
  url: "https://leshan.eclipseprojects.io/api/clients/IO_client/",
  payload: {"id": 1, "object": 26241, "resources": [{"kind": "singleResource", "id": 5601, "type": "FLOAT", "value": "13.1"}]}

The leshan server returns a 200 OK message with empty payload but the object is not enabled. :/

[sbernard31]

Yes, you are absolutely right and this is how we have done it so far but the Web UI does not give the option of creating new resources, right? only new instances.

Oh I don't get that.

You want to create "ressource" or you wanted to say "resource instance" ?
Because creating "ressource" doesn't make sense to me 🤔
And for "resource instance" this could make sense but this is not supported by LWM2M v1.1.1

See LWM2Mv1.1.1@core§6.3.6. Create Operation

The leshan server returns a 200 OK message with empty payload but the resource is not created. :/

That sounds strange but again give me a wget/curl and I can investigate.

[onovo1]

sorry for the confusion, I meant "enabling a new object" using the Web UI.

That sounds strange but again give me a wget and I can investigate.

This is a wget example to try to enable object 3333, for example. The server response with a 200 OK but the object is not enabled:

wget --method=POST      --header="Content-Type: application/json"      --body-data='{"id": 1, "object": 3333, "resources": [{"kind": "singleResource", "id": 5601, "type": "FLOAT", "value": "13.1"}]}'   --output-document=response.json      https://leshan.eclipseprojects.io/api/clients/IO_client/
--2023-11-09 13:47:38--  https://leshan.eclipseprojects.io/api/clients/IO_client/
Resolving leshan.eclipseprojects.io (leshan.eclipseprojects.io)... 23.97.187.154, 2a01:111:f100:9001::1761:93fa
Connecting to leshan.eclipseprojects.io (leshan.eclipseprojects.io)|23.97.187.154|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 0
Saving to: ‘response.json’

response.json                          [ <=>                                                           ]       0  --.-KB/s    in 0s      

2023-11-09 13:47:39 (0,00 B/s) - ‘response.json’ saved [0/0]

[sbernard31]

I meant "enabling a new object" in the client.

AFAIK, this is not allowed by the LWM2M specification too.

[onovo1]

that is related with the CREATE operation, right?

LWM2Mv1.1.1@core§6.3.6. Create Operation

[sbernard31]

that is related with the CREATE operation, right?

Yep, but more generally this has not so much sense to add support of an object just by sending a request.
I mean generally adding support of an object means "implement some specific behavior" at client side.

The leshan server returns a 200 OK message with empty payload

I was able to reproduce and even if REST API is not intended to be reused current behavior is not so good. I will adapt the code to return a BAD_REQUEST in that case.

[sbernard31]

The leshan server returns a 200 OK message with empty payload

Ok I fixed it with 73916b7
This is already in master (will be soon available in sandbox) and will be in next 2.0.0-M14 release

[sbernard31]

@onovo1 let me know if we should close this issue ?

[onovo1]

Ok I fixed it with 73916b7
This is already in master (will be soon available in sandbox) and will be in next 2.0.0-M14 release

thanks for such a quick fix!

I mean generally adding support of an object means "implement some specific behavior" at client side.

OK, I understand. So, the current behavior allowed on a server should be to request information and update the already existing objects, right?

I think we also got a 200 OK when trying to delete an objects from the server using the REST API, but such an object was never deleted.

[sbernard31]

OK, I understand. So, the current behavior allowed on a server should be to request information and update the already existing objects, right?

Yep

I think we also got a 200 OK when trying to delete an objects from the server using the REST API, but such an object was never deleted.

OK thx for reporting this 🙏
I will try to look at it (today or next week)

[sbernard31]

I think we also got a 200 OK when trying to delete an objects from the server using the REST API, but such an object was never deleted.

I tried that and get Bad Request

>> curl -i  -X DELETE  "http://localhost:8088/api/clients/mooky/3033"
HTTP/1.1 400 Bad Request
X-Powered-By: Express
connection: close
date: Fri, 10 Nov 2023 14:37:48 GMT
server: Jetty(9.4.51.v20230217)
Transfer-Encoding: chunked

Could you provide a way to reproduce ? 🙏

[onovo1]

Actually, the instance is deleted from the server and the client simultaneously:

curl -X DELETE "https://leshan.eclipseprojects.io/api/clients/IO_client/3442/0"
{"status":"DELETED(202)","valid":true,"success":true,"failure":false}

curl -X DELETE "https://leshan.eclipseprojects.io/api/clients/IO_client/3303/0"
{"status":"DELETED(202)","valid":true,"success":true,"failure":false}

Is that the right behavior?

Now, I remember, We expected that enabling an object instance on the server using the REST API would exhibit the same behavior as the DELETE operation, enabling the object in the server AND the client simultaneously.

[sbernard31]

Is that the right behavior?

Yep,

• Delete is about Deleting Object Instance. (See : LWM2Mv1.1.1@core§6.3.6. Create Operation)
• Create is about Creating Object Instance. (See : LWM2Mv1.1.1@core§6.3.7. Delete Operation)

There is no way to enable/disable the whole object at server initiative.

[onovo1]

There is no way to enable/disable the whole object at server initiative

Is there a way to create a new instance of an enabled object using the REST API, then?

[sbernard31]

Yep used by [Create] button in Web UI.

[onovo1]

Yep used by [Create] button in Web UI.

I meant, using the REST API. I was just wondering if currently that was possible.

[sbernard31]

Yeah it is possible using REST API.
Just click on [Create] button in Web UI, and use your browser devtools and you will see how to use the REST API.

Please, let me know is there is something unclear because I repeat myself several time on that point and I don't know how to explain it better 😬

[onovo1]

Please, let me know is there is something unclear because I repeat myself several time on that point and I don't know how to explain it better 😬

Everything is clear now, thanks. :)

[sbernard31]

Should we close this issue ?

[onovo1]

yes, please.

It would also be beneficial to have a proper documentation for the REST API. I understand that this may not be the highest priority given other important features that need attention, but having the documentation for the REST API would be a valuable addition, and it's unfortunate that the API is currently hidden.

[sbernard31]

having the documentation for the REST API would be a valuable addition, and it's unfortunate that the API is currently hidden.

Yep I totally understand you from a user point of view.
But as I explained, when we created our REST API, we didn't have in mind to make it reusable.
This API was just made to be used by the front-end UI of our server-demo.

So not so much effort was invest in it. Code quality of the demo is much lower than the library one.
And for now we haven't time enough to make it a "real component" with its own documentation.

Even if it seems that there is really a community need behind this :

• Interoperability tests wakaama/Leshan eclipse-wakaama/wakaama#617
• LwM2M interoperability tests [0 - 399] zephyrproject-rtos/zephyr#64013