(2024.2) API

Getting Started with the API

PCR-360 offers a REST API which allows an outside application to search and make use of your raw data. Using the API, you may retrieve your current Services, Cable, GLA, Equipment, and Service Desk records. Experience in software development is required.

To use the API, you'll need a unique API Key, which is used to identify yourself to the PCR-360 server and to protect your data. API keys are assigned permissions that dictate the API access. These are available on the API Permissions page. (Note: Do not share this unique key.)

Installations using the Shibboleth single sign-on integration for authentication will require an alternate URL/domain to make HTTP(s) requests to the API.

API Response Codes

Here is the list of Response Status Codes the API might return to your Requests.

Configuring REST Headers

Depending on the desired formatting of the request, there are two headers that can be sent. Depending on the 'Access Mode' for a User's Requests, other headers may be required.  Please see the API Permissions page for more details

Content Type: JSON

Encoding as JSON can be useful, but by default all API parameters are passed formatted as query-strings.

To activate JSON Content Encoding on a request, a header needs to be added to the request:

HTML Decoding

Special characters can be decoded on a per request basis. If special characters are being sent in your request, you can pass a special header to tell the API to decode each parameter.

To activate HTML decoding on a request, a header needs to be added to the request:

Logging

Logging can be enabled on a per request basis. This can be useful for debugging purposes; it will return a copy of the parameters that were submitted in the request.

To activate logging on a request, a header needs to be added to the request:

If the logging header is provided and the value is "true", the API Request will be returned in the response.

Output Formats

There are three formats the API can use for return data.

We currently offer JSON , PHP , and XML output formats.
(PHP returns a serialized array which can be converted back to an array using the unserialize() function)

What a Request Looks like

A basic request looks like this:

In this basic request example, a user of the API would replace the following:

More specific requests can be done by attaching more fields at the end of the URL in a query string:

Reading Data

When reading data via the API, the recommended method is to use the "sql" REQUEST type and specify a raw SQL query in the request. This will return the results of the SQL query in the response.

Request Types

SQL

The recommended method for reading data in the API is using the SQL REQUEST type. This allows you to specify a raw SQL query to the API and get back the results in the specified format. The SQL API request requires using the POST HTTP method.

Using CURL this example queries all records in the SERVICES table and specifies the content type is JSON encoded and requests data returned JSON encoded:

Using cURL this example queries all records in the SERVICES table using the default content encoding of HTTP query string parameters and requests data returned in XML format:

For more details, see API:SQL .

Cable

This REQUEST type is deprecated.

The cable REQUEST type allows access to PCR-360 Cables and related data. View full details on Cable API Calls.

Services

This REQUEST type is deprecated.

The services REQUEST type allows access to PCR-360 Services and related data. View full details on Services API Calls.

Equipment

This REQUEST type is deprecated.

The equipment REQUEST type allows access to PCR-360 Equipment and related data. View full details on Equipment API Calls.

GLA

This REQUEST type is deprecated.

The gla REQUEST type allows access to PCR-360 Service Desk items and related data. View full details on GLA API Calls.

Service Desk

This REQUEST type is deprecated.

This servicedesk REQUEST variant allows access to PCR-360 Service Desk items and related data. View full details on Service Desk API Calls.

Service Desk Actions

This REQUEST type is deprecated.

The servicedesk REQUEST type allows access to PCR-360 Service Desk items and related data. View full details on Service Desk Action API Calls.

Cable View Path Reports

The cable-view-path REQUEST type allows access to PCR-360 Cable Path Reports for a known Cable View Path. View full details on Cable View Path Report API Calls.

Custom Reports

The rpt REQUEST type allows access to PCR-360 Custom Reports. View full details on Custom Reports API Endpoint.

Getting LIST Values

Writing Data

The PCR-360 API allows an outside application to create or update Service, Equipment, or Service Desk items or submit SNMP traps. The basic write request is much like a read request; the URL is built in a similar fashion. Like the read requests, all API write operations are done via an HTTP(s) request (using cURL or some other method). You will need to build the URL to describe the request you are making.

The primary difference between an INSERT and an UPDATE is the presence of a “RECID” (unique record identifier). If a RECID is present, the system assumes you are trying to update that record. Whereas if there is no RECID present, it will perform an insert to create a new record and return specific information from the new record. The only exception to this is UDFs. An update can be made by supplying the RECID of the UDF value record or by supplying the Service/Equipment/Service Desk RECID and the UDF RECID. If an existing UDF value record is found containing these two RECIDs, it is updated rather than creating a new value record.

Failed Inserts / Updates

Business logic and database integrity checks are enforced when inserting or updating data. If the required data is missing or incorrect, an error will be returned with a status of "failure" and a description of the failure. Possible failures include missing required data, incorrect or missing foreign keys, non-compliance to application business rules or logic, and Custom Validation rules.

A common error that occurs is a required field missing from the write request. It is important to keep in mind that any required user-defined fields that are created for a specific service desk type will also need to be defined when creating or updating a record.

Request Types

Cable

The cable REQUEST type allows writing PCR-360 Cables and related data. View full details on Cable API Calls.

Services

The services REQUEST type allows writing PCR-360 Services and related data. View full details on Services API Calls.

Equipment

The equipment REQUEST type allows writing PCR-360 Equipment and related data. View full details on Equipment API Calls.

Service Desk

The servicedesk REQUEST type allows writing PCR-360 Service Desk items and related data. View full details on Service Desk API Calls.

Service Desk Actions

The servicedesk REQUEST type variant allows writing PCR-360 Service Desk Action and related data. View full details on Service Desk Action API Calls.

GLA

The gla REQUEST type allows writing PCR-360 GLA Records and related data. View full details on GLA API Calls.

Contact

The contact REQUEST type allows for adding and updating PCR-360 Contact Records and related data.  View full details on Contact API Calls.

Locations

The location REQUEST type allows for adding and updating PCR-360 Location Records and related data.  View full details on Locations API Calls.

Barcode

The barcode REQUEST type allows PCR-360 to interface with Barcode Scanning Devices to update Equipment Records.  View full details on the Barcode API Calls.

Custom

The Custom REQUEST type allows the API to invoke custom PHP logic that is saved in the application. This is very useful when interfacing with an application where you cannot control the format or data in the outbound requests. The structure of a custom request type is dependent on the identifier specified in the Custom Logic > API entry. For more information on the syntax and capabilities available in the Custom Logic > API interface, see Custom Logic Syntax.

Using cURL, this example invokes a Custom API called hello-world and the header specifies the content type is JSON encoded and requests data returned JSON encoded:

Using cURL this example invokes a Custom API called example using the default content encoding of HTTP query string parameters and requests data returned in XML format:

Writing UDFs

All the Request Types (Equipment, Services, and Service Desk) support writing to associated UDFs. Updating UDF values requires using specific syntax in the request data. Prefix the UDFs unique identifier with "udf_" and submit the values with the other request data.

API Request Log

For troubleshooting API Requests, navigate to 'Admin > API > API Request Log' to view a record of all Requests made to the API and the Response.  For more details, see the API Request Log page.

RECID vs. ROW ID

SNMP

Simple Network Management Protocol (SNMP) will capture events from network device(s). It is used for collecting information used on a form and configuring, network devices, such as servers, printers, hubs, switches, and routers. PCR-360 can listen for SNMP Events and set up automatic Notifications and Escalations according to the User or organizational needs. Currently PCR-360 supports both SNMPv1 and SNMPv2c. There is no support for SNMPv3 at this point in time.  For more information see the SNMP page.