API Reference Explained

The document is organized into two levels of hierarchy: 

• Class- General API classes that provide several types of access to an object such as BehavioralAssessments or Persons. Each of these are sometimes referred to an individual API (e.g. "the Persons API")
• Method- Individual API methods within each class that performs a specific action (e.g. GET behavioralassessments/{id} or GET persons/{id}) - 

Each level can be expanded or collapsed to show just the detail you wish to see. You may also notice that each section has its own direct web address so you can share links to specific API methods.

In each Method section, there are typically the following sections:

• Method title - a format string notation describing the spelling and sequence of the method and any parameters to be included in the request URL path.
  TIP: A normal integration can usually ignore the methods that use /companies/ in the URL since most integrations are configured with just one PI instance in mind.
• Implementation Notes - quite general, but sometimes makes important notes about limits on response content.
• Response Class - explains the structure of the response content returned upon a successful method call (response status 200). Note: if you click on Model, you will see the data types expected. If you click on Example Value, you will see sample JSON.
• Response Content Type - use only application/json  - ignore the text and XML options
• Parameters - pay attention to the Type column
• • path- you must include the parameter in the request as part of the slash-separated components of the path as shown in the format string in the method title
  • query- expected in GETmethods, the parameter must follow the question mark (?) and appear in key=value format separated by ampersands (&)
  • body- expected in POST or PATCH methods, a group of parameters must be structured as JSON. To place a blank parameter set into the Value text box, click on the Example Value in the Data Type column. Then you can edit the blank parameter set values as desired.  
• Response Messages - the format of any messages to expect. Be sure to build support into your integration that handles expected errors gracefully. Be sure to include support for HTTP response status 429 which indicates too many requests in a time period by performing an exponential back-off retry strategy.
• Try it out! - this button allows you to interactively test the method using live data if you are authenticated (see next section)

Testing with the API Reference

The API Reference page is designed to support interactive testing that will make real changes to the data of the connected PI instance.

Authentication

There are two methods of authentication available to allow you to perform testing:

• Log in to PI Software - if you first log into the PI Software, and then in the same browser visit the API Reference site, you can perform actions using the existing authenticated session using OAuth. Any requests you make will operate under the permissions of the user that is currently logged in.
• API Key - if you have an API Key generated for a user with permissions in a PI software instance, you can enter the API Key in the text box at the very top of the page labeled "api-key". With the api-key filled in, all requests performed in the page will include an HTTP header with the name api-key and the value you provided. Any requests you make will operate under the permissions of the user that owns the API Key.

Effects of Testing

Keep in mind that all actions taken via the API Reference page are always real -- they create or alter real, permanent data in the PI software instance. There is no "test mode" -- whatever you do via the API will generate email messages, alter data, and otherwise have the same effects as any action taken while logged into the PI software. 

If you do not believe it is safe to test the API using your production PI software instance, you can request a Sandbox Account for use in testing so your test data will not mix with your production data.

Performing Testing

The "Try it out!" button will submit whatever request is being shown with the parameters you may have filled in, and the results will be displayed just below the Try it out! button. The following sections will appear after you submit a request:

• Curl- the command line equivalent to the action taken by the Try it out! button using the cUrl utility program.
  TIP: Be sure you implement any of the required headers you see in the Curl command!
• Request URL - the complete URL of the request made by the Try it out! button
• Response Body - the JSON response content, if any, returned by the API after using the Try it out! button. If an error occurred in processing the request, error content formatted as JSON will be shown here.
  TIP: You should make intentional mistakes and see what error messages are shown here when you do.
• Response Code - the HTTP response code returned by the API after using the Try it out! button. Success response codes are in the 200 range. 400 or higher is an error.
• Response Headers - the HTTP headers included in the response from the API after using the Try it out! button.

Limitations of Testing PDF Output