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.

Status	What it means
200	The Request was received and executed successfully.
400	The Request was received, but contained Bad Data, so was not executed.
401	The Request was received, but your User permissions are not authorized to perform the requested operation.
403	The Request was received, but you lack the User permissions to perform the requested operation.
404	The Request was received, but the desired End Point was not found.
405	The Request was received, but you are not allowed to perform the requested operation.
503	This 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 .