(2024.2) Custom API

1 Basics
- 1.1 Logic tab
- 1.2 Debug tab
2 Prerequisites
3 Usage
4 Scope
- 4.1 $request
- 4.2 $response
5 Example
6 Syntax
- 6.1 UDF Identifiers
7 Invoking Custom API
8 Example

Basics

This feature allows the admin to define customized API routines. These routines can be executed via an API call using the Custom API identifier.

This Grid allows Users to add custom API calls.

Identifier: This is the unique identifier for the specific API logic. This identifier is used to invoke this Custom Logic with an API Call.
Description: A description field to provide additional information as to the purpose of the API logic.

Logic tab

The Logic tab is where the Custom Logic can be written and reviewed. A User can quickly review the code written for the specific event with the button. Users will be limited to the white-listed functions for PHP and some PCR-360 specific functions.. A list of the functions can be seen in PCR-360 by clicking on the button.

Debug tab

The Debug tab shows the results of debug function calls. This debug information is cleared after 24 hours.

Prerequisites

This feature is intended for Administrators and an understanding of PHP language and syntax is required. You must also be aware of language compatibility for the version of PHP installed on the webserver. For logic that requires querying other data, an understanding of SQL is necessary, particularly variants specific to your database platform.

Usage

In a typical API routine, incoming request data is processed and an outgoing response is built.

Scope

API routines are written and executed within a subset of PHP syntax and at run time they have scope access to two arrays of data $request and $response. For security purposes, only a subset of PHP functions have been whitelisted.

$request

A key/value paired array of the data that is POSTED to the API REST request. The contents of this request will vary depending on how and what is making the API request. There is no need to decode the $request data.

$response

A key/value paired array of the data that should be returned in the API REST response.

Example

Using cURL, we invoke a Custom API called hello-world:

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

The .json extension requests data returned JSON encoded
The Content-Type header directive for "application/json" specifies the incoming request data is JSON encoded

Within the Custom API logic, $request would contain the decoded request data:

array(
  "foo" => "bar"
)

The response can be built by assigning data to $response.

$response["hello"] = "world";

The given cURL request will return a JSON formatted response:

Syntax

Custom API shares a set of common syntax and available functions with the other types of Custom Logic.

UDF Identifiers

UDF parameters are all lower case when processed by PCR-360. Since Organizations can create their own UDF fields, the generic use of IDENTIFIER is used as a placeholder for actual UDF Identifiers.

Invoking Custom API

Read more about Making a Request for APIs and reading into the Custom API.

Example

This Custom API script was written to process incoming API calls from Slack (a team chat program we use internally at PCR).