I’m a developer on groov, and our just released R3.3a version includes a new place to store arbitrary data (we call it the Data Store), and our first public API: a way to get data in and out of those Data Stores. We also included support for CORS, so you can use it from a web page as well.
CORS can be a bit confusing, and on top of that a bunch of our customers use self-signed SSL certificates on their groov instances, so I thought I’d write down a getting started guide to get people past all of those bumps.
- Authorization to groov’s public API is provided via an API key. That key can be passed as a header, or via a query parameter. Each user in your groov project has an automatically generated API key, and administrators can generate a new key at any time.
- While every user has a key (it’s also used for Trend data downloads), the Data Store API is currently limited to Editor and Admin users only.
- In order to use the API from a web page, the domain that the page resides on must be whitelisted in your groov project settings. We don’t allow wildcard origins.
Getting at your API keys
There are two ways you can find your API keys. The official way is: an Administrator needs to log into groov Build and look in the Manage Accounts dialog. (Configure menu -> Manage Accounts…) API keys for your users will be listed there.
Remember, only Editor and Administrator users have access to the Data Store API.
The other, unofficial way is: log into groov, then in the same browser session
Whitelisting your domain for CORS access
In your Project Settings (Configure menu -> Project…), under General Settings, you’ll see
a configuration option titled “Allowed Cross-Origin Request Domains”. That’s the whitelist
for CORS access. You’ll need to add the domain where your webpage will live, as
well as a domain for where you’re doing your development. For example, this blog is built
using Jekyll, and as I’m writing this I have a local server running on port 4000,
so I’ll add
http://localhost:4000 as an allowed domain. Along with that, it will eventually
be deployed on my real website, so I’ll add
http://www.jonathanfischer.net as well. If
you’re developing without a server running,
file:// works, but in practice browsers seem
You’ll need to click the Save Settings button at the top of the Project Settings panel for changes here to take effect.
You’re on your own here. :) Basically, just visit your groov instance in the browser you intend on using and make sure it accepts your certificate without complaint.
Ok, here’s the fun part. First: the API is specced using Swagger, so if that’s
your bag you can use it to automatically generate an API wrapper. You can find groov’s
Swagger specification at Opto 22’s Developer Site (the groov part
might not be live yet), or on your groov instance at
/swagger.yaml. There’s also
a Swagger-UI installation running on your groov instance at
can use that to get a quick overview of what API calls are available, and how to use
So for example, if your groov instance is at
you can download the Swagger spec at
reach Swagger-UI at
Note: if you’re already logged into groov when you visit your Swagger-UI installation, you’ll be able to use all of the
GETendpoints in there without authenticating. groov has already set a cookie that the API endpoints recognize.
POSTendpoints will still require your API key though.
For the rest of this I’ll assume the groov instance is at
replace that with your own instance if you’re following along.
Let’s get a list of all the tags defined in your groov instance. The endpoint for
GET /api/v1/data-store/tags, and we’ll need to add our API key to it. The full
request we need to make then is:
looks like this:
And assuming all went well, you’ll see a response in your console log:
I might have been testing out Unicode support on that particular project.
Errors you might run into
- An HTTP 401 response means groov didn’t recognize your API key.
- An HTTP 403 response means the API key you used isn’t allowed to make that request. Remember, the Data Store only allows Editors and Administrators at the moment.
- An HTTP 404 response means your URL was wrong.
Along with those, you might just not get an error: your
load event handler won’t be called.
error handler will be called if you provide one.) That will happen when the
browser blocks your request for some reason (either it fails the CORS pre-flight check or
it doesn’t like your SSL certificate), or if you get your hostname wrong. As far I
can tell, the browsers won’t tell you the reason for the failure via the
you’ll have to look in your console log to figure it out. For example, if Firefox fails
the CORS pre-flight check, I get a generic error in my
error handler, but this helpful
message in the console:
Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource at https://jfischer-ar1.opto22.com/api/v1/data-store/tags. (Reason: CORS header ‘Access-Control-Allow-Origin’ missing).
Whew, that went longer than I thought. Have fun out there, groov users!
P.S. - Sneaky users might notice other endpoints being called by groov View. Basically, if it’s not under
/api/whoami, we make no guarantees that said endpoint will remain stable. They can and frequently do change between releases. Don’t rely on them.