Document toolboxDocument toolbox

(v1) .API v2019.7

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 (v1) 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.

StatusWhat it means
200The Request was received and executed successfully.
400The Request was received, but contained Bad Data, so was not executed.
401The Request was received, but your User permissions are not authorized to perform the requested operation.
403The Request was received, but you lack the User permissions to perform the requested operation.
404The Request was received, but the desired End Point was not found.
405The Request was received, but you are not allowed to perform the requested operation.
503This Response indicates PCR-360 is presently unavailable, and likely is in a Maintenance Window.


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 (v1) 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:

Content-Type:application/json

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:

Pcr-Html-Encoded:true

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:

Pcr-Debug-Api:true


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

    <equipment>
        <status>success</status>
        <page>1</page>
        <count>20</count>
        <total_count>3174</total_count>
        <equipment> ... </equipment>
    </equipment>
    <debug> .... </debug>

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:

CALLTYPE http://DOMAIN/api/API_KEY/REQUEST.OUTPUT


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

Parameter

Replace With

CALLTYPE

We support GET and POST call types, depending on the type of request.

DOMAIN

The URL used to access your PCR-360 application

API_KEY

The unique key generated by your admin

REQUEST_TYPE

The type of request being made. Recommended type is "sql". Other available (deprecated) types are: "servicedesk", "services", and "equipment"

OUTPUT

The desired output format.

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

GET http://DOMAIN/api/API_KEY/REQUEST_TYPE.OUTPUT?field1=value1 ...

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:

curl -X POST -d '{"sql":"SELECT * FROM SERVICES"}' http://DOMAIN/api/API_KEY/sql.json -H Content-Type:application/json


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:

curl -X POST -d "sql=SELECT * FROM SERVICES" http://DOMAIN/api/API_KEY/sql.xml


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 (v1) 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 (v1) 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 (v1) 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 (v1) 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 (v1) 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 (v1) Service Desk Action API Calls.

Getting LIST Values

To retrieve LIST values from the API send a request structured as below:

https://url/endpoint.json?LIST=VALUE

All List Types will be returned from the Endpoint the request was sent to. The format is different depending on the LIST requested, but should look similar to the example below.

{
    "status": "success",
    "page": 1,
    "count": 11,
    "total_count": 3,
    "sd_action": [
        {
            "RECID": 237,
            "VALUE": "Add"
        },
        {
            "RECID": 238,
            "VALUE": "Change Types"
        },
        {
            "RECID": 239,
            "VALUE": "Add Locations"
        }
    ]
}


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.

Use of HTML Tags

Some fields within PCR-360 allow Users to input HTML tags to make displaying that information a richer experience for those that are expected to consume it. For more information on HTML tag usage, please see the wiki entry for it.


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 (v1) 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 (v1) Cable API Calls.

Services

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

Equipment

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

Service Desk

The servicedesk REQUEST type allows writing PCR-360 Service Desk items and related data. View full details on (v1) 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 (v1) Service Desk Action API Calls.

GLA

The gla REQUEST type allows writing PCR-360 GLA Records and related data. View full details on (v1) 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.

Custom

Custom API is available starting in version 2.1.4.0
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:

curl -X POST -d '{"foo":"bar"}' http://DOMAIN/api/API_KEY/hello-world.json -H Content-Type:application/json


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:

curl -X POST -d "foo=bar" http://DOMAIN/api/API_KEY/example.xml


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.

{
    "udf_IDENTIFIER1" : "VALUE1"
    "udf_IDENTIFIER2" : "VALUE2"
    "udf_IDENTIFIER3" : "VALUE3"
}

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.

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.



Help Desk Portal - Email: help@pcr.com - Phone: 616.259.9242