Software Development Kit (SDK)

To assist developers, RPI provides :

• Detailed API documentation that is automatically updated with each release of Prism
• API-Explorer, a special interface for working with the Prism API

API Explorer
The Prism API Explorer provides developers with a convenient interface for:

• Viewing API information required for implementing customizations
• Making GET, PUT, POST, DELETE calls against the Prism APIs

Accessing the API Explorer

1. Point your browser to the Prism server, followed by: "/api-explorer".    For example: http://myprism.mycompany.com/api-explorer
2. Enter your user name and password and click the Login button.    
3. Select an area from the menu.    

Server Authentication Overview
Only authorized requests can communicate with the Prism server. Prism uses a type of server authentication called Digest authentication. In Digest authentication, the server sends a string of random data called a nonce to the client as a challenge. The client responds with a hash that includes the user name, password, and nonce, among additional information. This exchange and the data hashing make it more difficult to steal and reuse the user's credentials. A product of the server authentication process is a unique Auth-Session value. This is also known as the Session ID. The first API request that you make for a session should be a GET request that includes code for capturing the necessary values and generating the Auth-Session value. You can then include that value in subsequent API requests as an Auth-Session header.
Basic Steps for API Requests
1.    Perform a GET on http://{SERVERNAME}/v1/rest/auth  
2.    Perform a GET on http://{SERVERNAME}/v1/rest/auth?usr={USER}&pwd={PASSWORD} with both the Auth-Nonce and the Auth-Nonce-Response values in the header. Replace the {USER} and {PASSWORD} with actual values.  Read the Auth-Session value from the response. This is your session token that identifies your connection. The Auth-Session token must be present in the header of all subsequent calls made for your session.
3.    Perform tasks using REST methods in the API Explorer UI, or a tool like Postman.
Note: Subsidiary, Store, Price Level, Season
Certain API calls require values such as Subsidiary, Store, Price Level, or Season to be present. You may need to create scripts to capture these values for your API requests.
Server Authentication using Postman
Many users may opt for the convenience and community knowledge offered by applications such as Postman (www.getpostman.com).  An application like Postman makes it easy to set up variables, add pre-request scripts, headers, and other needed information.
The basic format of the GET request looks like this; however, for the GET request to work, we will have to define a Pre-request Script and headers:
http://{SERVERNAME}/v1/rest/auth?pwd=[password]&usr=[login name]
Sample GET request in Postman using environment variable prismServer with the login credentials of bb/bb:

Please note that the Basic Steps mentioned previously split the task of generating the Session ID and sitting the workstation into two separate steps. In Postman, we will combine those two steps within a single Postman GET request. Our single GET request in Postman will have three key parts: 1) a "Pre-request Script" that will run before the actual GET request and capture the "Auth-Nonce" values, 2) the GET request, which will do the actual log in, and 3) a test that includes the code to "sit" the workstation.

1.    Click  the New button to create a basic request.

2.    In the displayed dialog, enter a name and select a collection for the request.
 
3.    Click the "Pre-request Script" tab. This script will be run before the actual GET Request. This script performs a GET on http://{SERVERNAME}/v1/rest/auth   and captures the Auth-Nonce. The script also generates the Auth-Nonce-Response.
Note: The {{prismServer}} is an environment variable. Environment variables are explained later.

4.    Click the Tests tab. Simple tests confirm that we get a response code of 200 and that the response time is within 150ms. The next section of code captures the Auth-Session value from the response header and assigns the value to an environment variable. We define a variable, args, that has the details of the GET request that is used to sit the client workstation. The last part of the code sends the request. The callback function confirms the workstation is seated.

5.    Click the Headers tab. Enter Key/Value pairs.

6.    Now that the setup work is done, we can run the GET request. Enter the text of the GET request and then click GET. Replace the bb/bb login credentials with the desired RP Prism password/login name.

7.    If you defined everything correctly, you should get a response code of 200, indicating success.  Check the Auth-Session header. The Auth Session value returned in the header is automatically copied to our Auth Session environment variable. If you check the environment variables, the same value will be entered for the Auth-Session. You can then use interpolation to refer to the value instead of typing it out: {{Auth-Session}}

9.    Now that you have the authorization token for the session, you must include the Auth-Session variable in the Header section of subsequent API reqests.

Headers

Environment Variables
In Postman, you can define environment variables and then use extrapolation to refer to those variables in your requests and tests. Here is a sample of some environment variables

Auth-Session Header
After you have gone through the Authentication session, every request that you make back to the Server needs to include the Auth-Session header. What we're going to give you at the end of that Authentication process is a user token. That token uniquely identifies your session with the server. You must include that token in every request. If you don't include that token, the server treats it as an "out-of-band" session.
Request Types
GET
Use GET for fetching data from the server. The GET allows no request payload, but does return a response payload.
POST
Use POST to insert data into the system. The POST method sends a request payload and returns a response payload. Inserting a record may have other requirements, but one requirement that all resources have in common is the ORIGIN_APPLICATION attribute. You must provide an origin application in the payload for a POST to succeed.
PUT
Use PUT to update data on the server. The PUT method sends a request payload and returns a response payload. There is a filter requirement for PUT calls. When you GET a record from the server one of the attributes is row_version. This is used for opportunistic locking of records. To perform a PUT you must include a filter that includes the row_version. e.g. http://{SERVERNAME}/v1/rest/customer?filter=row_version,eq,37
DELETE
Use DELETE to remove a record from a collection. The Delete method accepts no request payload and returns no response payload.