Getting started with the PI Web API Beta

Discussion created by mhamel Employee on Apr 26, 2014

This is a copy of the blog of Brad Hess, Sr. Software Developer at OSIsoft


PI Web API provides basic functionality needed to retrieve and manipulate Time Series, Asset,  and Event Frame data.  Future releases will incorporate Indexed Search and OData capabilities.  We originally released a CTP in late November 2013; an updated Beta version of the PI Web API is now available in the downloads area here on vCampus. 


I'd like to provide some updated samples for how to retrieve some basic PI data using our latest REST APIs.  This post contains basic information that we think you'll want in order to get started regardless of client platform.  A subsequent post will contain walkthroughs and sample code for doing this programmatically, in both Javascript and C#.


Since all good samples need a story, let's say we're operating in the NuGreen database, and retrieving a listing of all the Pumps in the Houston plant.  For our first stop, let's just navigate to the root of the PI Web API at https://hostname/piwebapi




Thanks to the power of the new HATEOAS ("Hypermedia As The Engine Of Application State") functionality in PI Web API, navigating to resources is now as simple as following links in the product.


Before we dig into retrieving PI data using the Web API, let's first follow the HtmlHelp link.  The online HTML help provides API descriptions for all of the resources that are available in the PI Web API.




The links on the left refer to different groups of resources, or functional areas within the Web API.  The first set of resources is "AssetDatabases".  Since our starting point for our search is the NuGreen database, this is a great place to get started.  My AF server is named phlafs04, and my NuGreen database is named NuGreen, I'll just look it up by path.




Let's follow that link to get a more detailed description of that call:




All of the calls start with https://hostname/piwebapi/ .  What this documentation tells us is that there is a resource named assetdatabases that accepts a query parameter of path.  So, constructing the Web API call is as simple as combining all of that information together using HTTP syntax.  I'm going to call https://hostname/piwebapi/assetdatabases?path=\\server\database




And there it is-- the Web API information related to my NuGreen database.  Notice that the response contains links to other resources-- I can simply follow those links to drill into the database.  Notice that the links all contain long strings of characters that serve as identifiers for the various resources available.  These are referred to as WebID, and will definitely be the topic of a future posting here.  For now, suffice to say that they are simply opaque identifiers that we can use to uniquely identify various components in my PI System.




So we have our NuGreen database.  We'd like to search for Plants within it, in order to find the Houston plant.  One way we could do that is just by drilling into elements by clicking:






If we're going to do this programmatically, there's a more failproof way.  We can add a query to the database's /elements sub-resource.  Again, consulting the HTML help:




We're looking for an Element in the full hierarchy named 'Houston' that implements the 'Plant' template.  So we need to build that up as a query string:




Combine that with the link to the Database's elements from above to get:




And we'll end up with a result that looks like:




Great!  So the last step is to find the Pumps in Houston.  I.e., all the Elements underneath Houston that implement the Pump template.  Our query string will look a lot like the last one:






And there we have it.  All the pumps in Houston.  Stay tuned for our next post, where we'll do this in code.