THIS CONTENT IS OUTDATED. See http://vcampus.osisoft.com/bloggers_place/b/webservices/archive/2014/04/17/getting-started-with-the-pi-web-api-beta.aspx for the latest version of this post.
As mentioned in Dan Noonen's post on the Product Management blog, PI Web API Core Services provides basic functionality needed to retrieve and manipulate Time Series, Asset, and Event Frame data. A CTP of the product is available now, in the downloads area here on vCampus. The PI Web API Core Services is trying out a new "rapid release" trajectory, wherein improvements in prerelease versions of the product are made available to the vCampus community as soon as they're stable and tested. Hopefully this will accelerate feedback for our team, while giving our vCampus community earlier opportunities to familiarize themselves with upcoming functionality.
A few caveats to know before installing the CTP that's available today. First, there's no SSL--for now, all requests are made of plain HTTP/port 80. Second, there's no granular security. For now, all requests to retrieve or modify PI data is done under the Service Account that runs the Windows Service (Network Service, by default). Of course, both of these items are items that we attend to address in a subsequent release.
As a final caveat, the CTP contains instrumentation that automatically reports data to OSIsoft. Please read this information carefully in the installation kit, and ensure that you agree to the terms before installing the product. More information about this instrumentation is the topic of a future blog post.
Since all good samples start with a story, we'll just say we'd like to start with the NuGreen database, and get a listing of all the Pumps in the Wichita plant. Our first stop is the online documentation for the Core Services, located at http://your-server-name/piwebapi/help. Feast your eyes on the beauty of this pre-release documentation.
Since we know that Houston is an AF Element, and so are all the pumps underneath it, it seems like an AF Element Search is a good place to start. And there it is-- right near the top-- Retrieve elements based on the specified conditions. We can click on the link there to get more information.
Note that many of these parameters are optional. The only ones that are required are the ones that come before the URL query string-- i.e., before the question mark. We must provide a PISystem and a Database in order to do a search. All other parameters are optional, and have (hopefully) sensible defaults.
In fact, leaving all the optional parameters empty will return every element in the database! That won't help us much, so let's look for what we want to filter on. It appears that we can specify an Element ID as a search root. That'll come in handy when we want to find all of the Pumps that are under Wichita. So our first step is going to be to get an Element ID for Wichita, so that in a subsequent call we can find all the Pumps in Wichita. Based on the NuGreen layout, the Wichita element will be the only result when we search for a Template of 'Plant' and a NameFilter of 'Wichita', and of course adding our required parameters of AF Server and Database. To test our theory, we can try executing this GET from a browser. After all, REST services are just HTTP.
A couple of things to notice here. First thing is that these URLs are case-insensitive. You needn't worry about the capitalization of URL variable names.
Second is that, if you're not using Google Chrome, you might get your results in JSON format instead of XML. Why's that? It actually has to do with the design of your browser. The default format provided by PI Web API Core Services is JSON. However, if you specify a preference in the 'Accept' HTTP header, the PI Rest Services will actually honor your preference. Google Chrome by default sends an Accept header that asks for XML. In this case, since I called the API from Google Chrome, I got XML back. We can actually see this interaction if we watch the network request in Chrome's Developer Tools:
Good to know-- as a developer, you can retrieve either XML or JSON from the services provided by OSIsoft. The Accept header is your ticket to doing that.
Alright, so anyway, back to our story. From the output we've gotten in the browser window, we now have the ID of the Wichita Plant, which in my database is 'f675274f-80f4-4a85-87e6-bbb83a9e0293'. In your own NuGreen database, the chances of this GUID being identical are essentially the same as that of the universe coming to an abrupt halt before you finish reading to the end of this sentence. So use your own Wichita ID for our next steps.
This brings us to an interesting conundrum, which is definitely the topic of a future post here. The question is-- is it safe to hardcode that ID into my application? It depends on your use case, but my blanket suggestion without knowing your use case is that that's probably not a safe thing to do. When we write our client application in my next post, we'll assume that this interaction will take place in two steps-- first get the ID for Wichita, and then get the list of Pumps underneath it. More on this topic at a later date!
So we have our searchRoot, and we know we want pumps. All this is going to take is another call to the same API, with those parameters specified:
And there we have it. All the pumps in Wichita. Stay tuned for our next post, where we'll do this in code.