PI Web API: Quick Start

Version 3

    PI Web API is a RESTful PI System access layer that provides a cross-platform programmatic interface to the PI System.  RESTful interfaces enable cross-platform development of web, desktop, and mobile applications across many different programming languages.  PI Web API enables you to retrieve and manipulate time series data from the PI Data Archive as well as asset and event frame data from the PI AF Server.

     

    Here is a summary of some of the core functionalities available from the PI Web API.

    Area

    Functionality

    AF Server(AssetServer)

    Create, retrieve, update, or delete elements, attributes, and templates

    Create, retrieve, update, or delete Event Frames and their attributes and referenced elements.

    PI Data Archive (DataServer)

    Create, retrieve, update, or delete PI Points and Enumeration Sets

    Data

    Retrieve snapshot, recorded, plot, interpolated, or summary data from streams (attributes or PI Points); Post new events to streams

    Search

    Fast indexed searching of PI and AF objects such as elements, attributes, and PI Points

     

    Background: What is a web service?

    A web service is a method of communication provided at a network address over the web. It is commonly used as a means for businesses to communicate with each other and with clients, as it allows organizations to communicate data without taking into account different IT infrastructures. The most common models of web services used are the SOAP and REST models of communication.

     

    Quick Things to Know about PI Web API

    • The PI Web API is a RESTful web service.  RESTful web services work just like websites. You enter a URL and receive back some data.  Typically, a web page will return content in an HTML format, but with the PI Web API, you receive data in JSON format.
    • Try it yourself!
      • Connect to your local PI Web API with the browser of your choice by typing in the following URL:

        https://<your Web API machine>/piwebapi

        https://<your Web API machine>/piwebapi/help

    st-widget-{image: piwsarch.png}
    The figure is an architecture diagram of a typical deployment of PI Web API.

     

    Example: Browse your local endpoint

    In the previous section you were requested to navigate to your local endpoint or to our public endpoint.  If you did that, you should have seen a page that looks like the one below.


    On the homepage, you are at the top of the hierarchy.  This means that you can access any resource on your PI Data Archive or AF Server, provided you have the appropriate access, by navigating down through it.  You can look at your AF Elements, Attributes, Event Frames, etc. by clicking on AssetServers or you can look at your PI Points by clicking on DataServers. 
    Try this yourself!  Pick an Element, Attribute, or Event Frame in your AF Structure and try to find it by drilling down through AssetServers.  Try the same with a PI Point in DataServers. Take notes of the URLs as you work your way toward the object. 
    It’s fine if you can’t find it, there’s still more to learn about how the PI Web API works!  If you’re determined, use the online help mentioned in the previous section to give you an idea of what types of URLs you would need to enter to reach the asset you are searching for.

     

    HTTP Verbs

    Hypertext Transfer Protocol, more commonly known as HTTP, is a request/response protocol; your computer sends a request and the web server responds with what you requested.  But how does the web server know whether you want to create a new object, delete it, read it, or update it?  This is where HTTP verbs come into play.  There are many different HTTP verbs, but we will focus on 5 main ones: GET, PUT, PATCH, POST, and DELETE.
    GET: Read data from the server.  Don’t modify anything!  In the previous section, we made a GET request to the PI Web API homepage.

    PUT: Create or update a resource.  PUT is idempotent; subsequent calls with the same input parameters will have no effect.

    POST: Create or update a resource. Unlike PUT, multiple POST requests will result in the creation of many new resources.

    PATCH: Modify part of an existing resource. If a resource has many fields, you would use a PATCH request to change one of those fields.

    DELETE: Delete a resource. DELETE is also idempotent.

     

    PI Web API WebIDs

    A question often asked by newcomers to PI Web API is “What is this WebID thing and why I must I use it when creating a RESTful request?”
    When you retrieve information, PI Web API encodes both the ID and the path to the requested object to form a WebID. The WebID forms a new, redundant, unique identifier for use in further queries. Most PI Web API queries require that one or more WebIDs be included in the call.

    When you make a query with an input WebID, PI Web API decodes the WebID and finds the object's unique ID along with the object's path. PI Web API then attempts to perform the query using the object's unique ID. If the query fails, PI Web API performs the query using the path instead. This gives the PI Web API a redundancy-protected, efficient way to reference objects in the PI System. As such, it is safe to persist URLs that contain WebIDs over long periods of time.

     

    Example: Make a Request 

    Now that we know about HTTP Verbs and WebIDs, it’s time to get our hands dirty by making some requests to a PI Web API endpoint.  The next big questions to ask are, how do you construct a PI Web API call and how do you know what type of response to expect? The best place to look for these answers is the online help provided by the PI Web API service. You can view the online help by opening a web browser and navigating to https://<server-name>/piwebapi/help.  From this documentation, you can see all of the PI Web API queries available with your current version.  This information is also available here if you are using the most recent version.  Each entry in the help will indicate the required HTTP verb, URL, and if necessary, JSON format to execute a particular action.
    Using your favorite REST client (POSTMAN, Fiddler, Advanced REST Client, etc…), you can make calls to your PI Web API server to retrieve or write data to PI.   Let’s do so now by finding the “sinusoid” tag and writing a new value to it.  Most PI Systems have this tag included by default.  If you don’t have it on your system, feel free to create a new test tag for this exercise.  Do not use a tag that is tied to any important data!


    First, we have to find the WebID our PI Point.   I’ve used the point controller in this example but there are multiple ways to do this.  Take a look around the documentation to see if you can find others!

    https://<server-name>/piwebapi/points?path=\\<pi-data-archive>\sinusoid


    Here’s the result of the query in Postman:

    Your WebID is very likely to be different than mine, please make sure to get the correct ID from your server. If this call does not look like it returned any data, look for the HTTP response code (called Status in Postman) to determine what the issue is.


    Now that we have the WebID, it’s time to write to the point.  We will be making a POST request to  the stream controller to do so.  The URL we will use is:
    https://<server-name>/piwebapi/streams/<WebID>/value

    We are writing data into the web server so we will need to accompany our request with some content.  This content, such as the one pictured below, is known as the body.

    If the write is successful, you will get an HTTP response code of 202 Accepted.


    Congratulations, you’ve now made a GET and POST request to your PI Web API server and finished the Quick Start document!  Are you hungry for more PI Web API knowledge? Check out the PI Web API Useful Links Nexus (linked in the Additional Resources section below).  You will find examples, interesting projects, and version information.  If you prefer learning through documents, Developing With the PI Web API White Paper is a good next step.  If you prefer examples, the Programming in the PI Web API course is your best bet.

     

    Additional Resources