|
Chris Cicchitelli Administrator Posts: 3390
3/2/2016
|
OK cool, thanks!!
|
|
|
0
link
|
|
Tommy Long Posts: 218
3/3/2016
|
Yes PHP please 
|
|
|
0
link
|
|
Michael Wallace Posts: 52
3/5/2016
|
Chris, can you post a quick http example call to turn a group named Group1 to on as well as another to check whether Group1 is on? Thanks.
|
|
|
0
link
|
|
Phil Hawthorne Posts: 400
3/7/2016
|
Chris Cicchitelli wrote: Documentation is built in, if you use a REST or WCF discovery tool, it will all put up automatically. You have Visual Studio installed right? A WCF tool is built in. Do a search on the start menu for WcfTestClient.exe. After it opens, right click My Service Projects and select Add Service. Then enter http://localhost/CastleOS/service
You'll see two entries for each, ignore the ones with red Xs, those are the REST versions of each function... Ok, so after a bit of Googling I now have those endpoints. I'm focussing on the red X's, because I want to use REST. I went through the webapp, and most of the calls actually return the HTML content. For example, a call to devices.aspx returns the HTML to render the webapp. Not the API as you mentioned. The raw ASPX files don't make any calls to CastleOS, apart from a "codebehind="devices.aspx.cs"" which I can't seem to locate.
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/7/2016
|
So it looks like all the methods are there, but the discovery of those methods isn't working, so without knowing which to call direct you can't do anything. Let me see how to get discovery working on the client side (like I said, I'm not a REST expert so I'm learning too...the WCF side I know well).
|
|
|
0
link
|
|
Michael Wallace Posts: 52
3/11/2016
|
Chris, if you can get some of the basic REST commands up, I can extrapolate proper use of the others. Some examples are a group or device or scene toggle and status of the same. Given this, I can give a prelim dashboard interface that incorporates weather, traffic, newsfeeds, CastleOS controls, and full Sonos control that is along the lines of Dashing.
edited by rpiwally on 3/11/2016
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/12/2016
|
And we officially have a working secure REST API & demo! Going to add some more documentation to the demo and will get it up ASAP...
|
|
|
0
link
|
|
Phil Hawthorne Posts: 400
3/12/2016
|
Chris Cicchitelli wrote: And we officially have a working secure REST API & demo! Going to add some more documentation to the demo and will get it up ASAP... Hey Chris Great news. How did you solve the security issues? I hope its not a complicated process to get access to the API
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/12/2016
|
It was actually a pretty simple solution (code wise) once I figured it out, and it's very simple to use. First you authenticate the user with a username and password, and if it works, store the username and token. then, you pass the username and token as a header with all subsequent calls to the API. That's it!
I have a jquery example up and running, want to try?
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/13/2016
|
I just posted to the beta folder the update you need to use the API, and a file named jQueryRestExample.html. Check out the source code of that file, it should work if you open it in the browser after you install the update.
At the moment I'm exploring how to fully expose the documentation that's in the API via a Visual Studio tool, as well.
|
|
|
0
link
|
|
Phil Hawthorne Posts: 400
3/13/2016
|
Hey Chris
This is fantastic! I'm going to start checking this out right NOW.
Quick inspection of your jQuery examples seems ok. How long are security tokens valid for?
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/13/2016
|
90 days, but you guys can convince me to get rid of the expiration if you try hard also, if you use "kinect" anywhere in the username, it won't expire (it's a hack for kinect services so they don't randomly stop working one day on headless machines).
|
|
|
0
link
|
|
Phil Hawthorne Posts: 400
3/13/2016
|
Excellent. I just fired it up, and got one of my scenes to list. Looking promising. Looking at the way the API works, its no way near REST compliant. See http://stackoverflow.com/a/671132 for what a REST API would really be like. For example, everything is using GET. To toggle a device on/off in a RESTful way I should be using POST or PUT. To get the status of a light, I would use GET. This isn't a huge thing, but it will mean you'll have to spend a lot of time making examples for each endpoint, unless there's a way for the API (over HTTP, not a Visual Studio Tool) to tell us how the API expects data.
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/13/2016
|
It's REST compliant. jQuery is abstracting all the JSON CastleOS is returning, but it's standard JSON. As far as the GET-only, that is by design, as asynchronous services should only implement GET for performance reasons.
As for as the documentation, it's all there internally, but there's no easy way to translate that into something that we can post online. So I just put up a contract for someone to translate our internal docs into a pretty web page we can post on the site. Hope to have that done in a few days. In the meantime, if you need a specific example, let me know...
edited by ccicchitelli on 3/13/2016
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/13/2016
|
Phil Hawthorne wrote: (over HTTP, not a Visual Studio Tool) Btw, I knew as soon as I posted that I didn't phrase it well... I meant us using a tool to build the docs automatically. Can't do it with what we got, so on to plan B...
|
|
|
0
link
|
|
Phil Hawthorne Posts: 400
3/13/2016
|
Chris Cicchitelli wrote: It's REST compliant. jQuery is abstracting all the JSON CastleOS is returning, but it's standard JSON. As far as the GET-only, that is by design, as asynchronous services should only implement GET for performance reasons. Err JSON does not equal REST compliant. I've never heard the GET-only reasoning. Not sure if that's true. As an API only offering GET-only, you'll severely limit the data that can be pushed into CastleOS. Example, each attempt to create a new scene will require 1 call to the API. To update 3 device statuses to on, 3 API calls must be made. By the law of the internet, a URL has a maximum length. Once that gets exceeded, the call fails. However, with POST, in one call to the API the caller can POST you a JSON object, with all the IDs of devices that need to be turned on. Or, the JSON object could also have different states for different devices. Example, device 1 status ON, device 2 status off. In one API call this reduces latency and overheads by a huge amount.
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/13/2016
|
There is a length limit, but at 2083 characters I can't think of what will hit it. I guess the REST versions of the AddEvent, AddScene, etc could hit it, so we'll have to reevaluate that. But in terms of command and control, you should be good to go.
Keep in mind a GET is a single request, while POST is multiple, so it's much faster this way. When you're updating three devices statuses you'll be calling the API three times anyways because the API is only designed to handle one at a time anyways.
Don't get me wrong, I'm not trying to be dismissive, we can and are willing to change anything here that's needed. The REST API is for you guys, we use the WCF API for the CastleOS app. So test away and let us know what you need!
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/13/2016
|
Btw, regarding my JSON comment, we're not doing custom JSON or anything, we're using the standard .NET capabilities to generate it, and .NET (in theory) generated "compliant" code. Like I said, if you find issues, please point them out!!
|
|
|
0
link
|
|
Phil Hawthorne Posts: 400
3/13/2016
|
Chris Cicchitelli wrote: There is a length limit, but at 2083 characters I can't think of what will hit it. I guess the REST versions of the AddEvent, AddScene, etc could hit it, so we'll have to reevaluate that. But in terms of command and control, you should be good to go.
Keep in mind a GET is a single request, while POST is multiple, Yeah those two areas are what I'm thinking will be the possible reasons requiring POST. Once you start thinking about veriable names, and all the options that need to go in them, that 2083 characters can get chewed up very fast. Also regarding POST, I'm not sure how CastleOS/.NET handles POST requests, but from a HTTP perspective they are all the same number of requests: 1. The difference being how the data is pushed to the receiver. I'm writing a PHP wrapper tonight, so will let you know if I run into any roadblocks with it. I used the WCF Discovery tool the other day to get the API endpoints you mentioned (the ones in red). Are they still the same endpoints I can use? Is there any info on how the data is accepted outside of the examples? Can I see them from that WCF Discovery tool?
|
|
|
0
link
|
|
Chris Cicchitelli Administrator Posts: 3390
3/13/2016
|
Two things: the Unsecured Service had a bit of consolidation, so refresh that. Also, I'm going to send you the internal docs, it should help you a lot. Will come in PM..
|
|
|
0
link
|