PRIS

The Pitram REST Integration Services (PRIS) provides a way for external systems to access Pitram and Pitram Portal services via a Web API Interface, for the purposes of retrieving or updating the Pitram data.

Integration through PRIS guarantees backward compatibility of the integration layer in future Pitram releases. If a specific integration service does not exist, it is recommended that a new PRIS service, or services, be added as opposed to a direct low level integration through the Pitram databases.

This content is intended to be used by technical or software development personnel for the purposes of configuring or developing systems external to Pitram. The intent of these external systems will be to request or submit information from or to the Pitram system.

Architecture Context

Since PRIS are based on REST, any client application, on any platform, written in any programming language, may interact with services using a simple URL on top of HTTP. The PRIS server is hosted under IIS.

There are some cases when we need to stray from the REST guidelines and take a more pragmatic approach. An example of this is if we have a large amount of input data for a GET. In this case, the route will use a POST, and the route will generally end with an action verb such as “search”. When we use a POST in this way, a large amount of input data may be included in the POST body, rather than having to rely on very long URL parameters.

URL Syntax

• Parameters in braces ‘{}’ are compulsory unless otherwise stated. They must be passed to the URL to locate the particular resource and successfully complete the request.
• Optional parameters will be passed via query strings (e.g. ?{optionname}={paramvalue}, and these will always have some default value.

• If a parameter is used more than once in a PRIS call, only the last instance is applied.

Base URL

URLs in this documentation have the following base:

http://{PRIS server}/{pris}

Where:

PRIS server is the server name (if able to be resolved to IP address through DNS) or the IP address of the PRIS server, and

pris is the name of the virtual directory configured under IIS, that contains the PRIS Web API (default is pris)

Response and Errors

The success of a PRIS Request is communicated via the HTTP Response using standard HTTP response codes.

Successful GET operations are returned with the requested data and a Response Code of 200.  PRIS will use content negotiation to return either JSON or XML, with JSON being the most common format. The shape of this data will be documented with each specific URI.

Successful POST operations will return a Response Code of 201.

An error condition for either a POST or GET will contain a Response Code other than 200. Where the PRIS server is able to add more error information, the Response will contain the following structure:

PRIS Error Structure Shape

Field	Value
code	An error code returned from the PRIS server
message	A brief description that can be presented to the user