Ιn this video I want to introduce where to find and how to use the PI Web API developer
documentation, also known as the help files. Εvery PI Web API installation comes with a
local installation and help files. Ιn the upper left hand corner of the main landing
page for the PI Web API there's a link to the help files. When clicking on this link a new
tab is open to the main help landing page which describes each of the sections of the
help documentation. Let's take a quick look at the getting started help page.
This page contains some background information about restful Web APIs generally as well as
HTTP status codes JSON as well as a sample PI Web API response message. Towards the
bottom of the page it also has the code for a simple JavaScript application.
Additionally we also have a change log in the PI Web API help files,
this allows you to quickly see what new features have been included in each version.
The controller section is where we'll be spending most of our time. Controllers
are top-level endpoints on the PI Web API. They're named after each of the data archive
or AF server objects and their resources. For example if you're interested in getting
or changing information on an AF element we can click on the element controller link.
Each controller has a list of actions that we can perform on it. In this case we can get or
create an attribute as well as update, delete, among other options. Each controller action has
additional information about the call when we click on the action itself. Let's check out the
GetByPath action on the elements controller. There are a number of important pieces of
information contained here. The HTTP verb that we need to use to execute this action, the form
of the URL this action takes, so this will be what follows the base URL. In my case the base
URL is https://venus.holst.dev/piwebapi. Under the URL parameters we have the path parameter,
we see it's not listed as optional so we know it's required to make the call. In certain cases
parameters will be listed as optional and defaults will be taken if nothing is specified for them. In
general to use URL parameters we're going to need to use a question mark, then the name of
the URL parameter, followed by an equal sign and whatever the value of that parameter is.
For this particular parameter we have additional information on the syntax that is linked from the
URL parameter description. If we had multiple URL parameters we would use an ampersand after
the first URL parameter. For example, if we're making a GetRecorded data call on an attribute
we have the option of specifying the start time and end time. The PI Web API additionally tells
us what status code to be expecting for the response so we know ahead of time what a
possible good value is. Lastly the PI Web API help file tells us what the sample response is
going to look like. Alternately it may also tell us what the request body is expecting
to see which we can copy and paste to help us cut down on syntax errors when posting.
Aside from the controllers there's a list of topics in the PI Web API help files that you
might find interesting, such as path syntax with a query syntax information that you may
need to use in conjunction with the controller and action information. Lastly, I want to note that in
addition to the locally installed help files there is also an online copy of the same documentation
for the most recent release of the PI Web API hosted on the OSIsoft tech support webpage at
the following URL. We'll be referencing these help files periodically throughout the course.
I encourage you to do the same if you ever find yourself stuck on either syntax or needing to
find out how to complete a task. You'll occasionally find that there are multiple
methods to accomplish the same goal and what to use is up to your preference.