Controller v5.12 new openapi endpoints

[evanjarrett]

In version 5.12 they now have released a more documented API with support for oauth and client tokens.

https://community.tp-link.com/en/business/forum/topic/619304?sortDir=ASC&page=1

Open API: Omada Controller now supports Open API integration. You can access it through Global view > Settings > Platform Integration, which allows you to utilize the REST API of most Controller services. This feature enables you to develop custom applications, embed APIs, or combine your own applications. Refer to the Online API Document for guidance on usage, and view more by toggling the drop-down menu in the upper left corner.

The main difference in the urls is the /openapi/v1 endpoint, and some of the parameters are changes currentPage -> page

There is even API docs now hosted on the controller itself
(however, the page is terribly slow on my oc200, i don't think its powerful enough for whatever they are doing to generate them)

Does this repo have any intention on supporting this new "openapi" they have? I think it would be very useful for applications like home assistant to be able to use the new client tokens instead of username/password.

[MarkGodwin]

Yes, I'm aware of the new API. Unfortunately, it isn't anything like the original API, and as a v1, I'm a bit worried about how stable it will be at this stage.
I'm a bit busy with other things at the moment, but I will investigate switching over to this. I have the same experience of the OC200 being completely incapable of showing the API documentation.
To be useful for a back-end case, we'll need to use the client_credentials flow anyway, which isn't much better than username/password. The interactive flow works fine for end users, but the refresh tokens you get from it aren't good for more than a few days at most.
The biggest problem seems to be the API call limits, which are really low. I don't know why there would be API limits for a local API like this, unless TP-Link is doing some cloud processing to support the API.

[evanjarrett]

With the open api schema, I was able to run their new one through a api generator and come up with at least some usable (but ugly) python code https://github.com/evanjarrett/omada-open-api
But I don't exactly want to maintain a completely separate api client when this repo exists and is already used by others.

I expect it will change over time, but if they do maintain openapi specs and versioning it shouldn't be hard to update.
If the docs are true, the 1000 per day limit is tiny. I would need to test if i actually hit a limit. I have a feeling the docs are just wrong.

[MarkGodwin]

My Omada controller shows an API call counter, and it gets used up fast. My plan is to wrap the new API with the existing package interface so that anyone using it doesn't have to update. However, I haven't looked at how feasible that is yet.

[MarkGodwin]

@evanjarrett Have you had much success with the OpenAPI endpoint? I'm considering making the switch, but I'm concerned about the API call limits. Are these being enforced?

[evanjarrett]

I looked into this today, it is being enforced....
error_code=-7132, msg='Our server is receiving too many requests now. Please try again later.'

I didn't dig in too closely, but I couldn't find a way to see the API call count via the responses until you hit that error message.
Also, my generated python api clearly shows some documentation problems. just trying to get client details is broken because they aren't returning the data as defined in their openapi schema, and that was after i spent a good chunk of time just fixing up syntax errors in it.

I think the next course is to suggest they change the api limit on their forums, and maybe submit a fixed openapi schema to help them jump start proper documentation.
This is all clearly a step in the right direction, but I don't think its ready for anyone to actually use yet.

[evanjarrett]

It appears there may be some changes coming to the rate limit, but I'm not sure what version they would be in.
https://community.tp-link.com/en/business/forum/topic/253944?replyId=1291284
This post points to a hosted version of their openapi docs
https://use1-omada-northbound.tplinkcloud.com/doc.html#/home

which states Note: Open API visits are limited to 10 visits per MSP/customer per second.
the beta 5.13 docs don't mention anything related to this change,

[mheath]

@evanjarrett Are you seeing the rate limiting when connecting directly to the controller or is that going through the TP Link cloud?

[evanjarrett]

Directly to my controller's IP address and API.
I don't have cloud access enabled.

[MarkGodwin]

TP-Link is going to remove the new Open API from the OC200 controller, so this doesn't look like it's going to be a good long term option either.

[evanjarrett]

Yeah unfortunately its going away for the OC200. Really lame of them, I think they just undersized the hardware for that controller in general, because mine is always really slow navigating etc.

That said, with the latest update v5.14 it seems like the 1000/day cap and the 10/sec cap are removed on my controller.
I was able to get ~15 per second and had done a few thousand requests. Also looks like my project I hacked together a year ago still works fine, at least for fetching client details.

For this project, I don't know if its worth investing time into open API if they are going to end support for their "home-user" device only a year after they added it.

[MarkGodwin]

Yeah, I'm going to close this for now. If TP-Link reverses their decision, I'll consider switching over.
My guess is they are going to stop updating the OC200 software before too long. I might pick this up again if I move to using the software controller in an HA supervisor container.