Pega API for Pega Platform 8.1
The Pega API provides a standard set of services that includes case creation, assignment processing, and access to data pages. These built-in REST/JSON services enable the rapid implementation of Pega mobile and client applications. By default, Pega API services are secured with user credentials and TLS/SSL connectivity. In addition, some APIs require your access role to have specific privileges before you can use the API.
Pega API services
You can call any of the Pega API services by using standard HTTP methods (for example: GET, POST, or PUT). Refer to the Pega API resources page in Dev Studio or Admin Studio to see details of the request and response data requirements. This documentation is also available in JSON format in the Docs API (GET/docs).
The following Pega API services are included with Pega Platform™:
- The Application APIs include:
- Cases API, which you use to obtain a list of cases for a user, create a case, obtain case details, and update a specific case.
- Casetypes API, which you use to obtain a list of case types for the authenticated user.
- Data API, which facilitates the process of obtaining the contents of a data page and obtaining the metadata for a specific data page.
- The DevOps APIs include:
- Applications API, which you use to get application, get application details, get quality and metric guardrail details, and start and stop application coverage.
- Branches API, which you use to get branch conflicts, merge branches, get and create branch reviews, and get the summary for a branch.
- Merges API, which you use to get the merge status.
- The System Management APIs include:
- Nodes API, which you use to start and cancel quiescence (immediate drain or slow drain) on any node in the cluster, list the current configuration settings for a node or the whole cluster, download the prconfig.xml file, and list the nodes that are in the cluster.
- Caches API, which you use to manage various caches in Pega Platform, for example, to manage the in-memory VTable cache for a specific rule class and instance name; to clean the cache; repopulate the cache; and get cache statistics for the authenticated user.
- Agents API, which you use to fetch the agent list, get agent details, and start, stop, and restart agents.
- Job Schedulers API, which you use to fetch the job scheduler list, and start and stop job schedules.
- Pools API, which you use to manage requestor pools, for example, to clear a requestor pool or list all requestor pools on the specific node.
- Queue Processors API, which you use to get all queue processors, and start and stop queue processors.
- Reports API, which you use to get the module version, conclusion cache, log usage, MRU, property reference, database, properties, and tables reports.
- Requestors API, which you use to get the requestor list, get requestor details, and stop and interrupt requestors.
- Loggers API, which you use to get log categories, reset log categories, fetch logger details, and set the log level for a category.
- The User Management APIs include:
- Authenticate API, which you use to verify user credentials.
- One-time password (OTP) API, which you use to verify an OTP and generate and send an OTP to a user.
- User API, which you use to terminate and disable user sessions, and enable disabled users.
- The Data Privacy APIs include:
- Client requests API, which you use to create new client requests for access, rectify, and erase.
- Data privacy metadata API, which you use to get field names for identifying clients.
- Client usage restrictions API, which you use to update client usage restrictions.
- The Docs API provides the complete documentation for the Pega API.
Accessing the Pega API help
You can access the Pega API help documentation from either Dev Studio or Admin Studio.
- In Dev Studio, open the Pega API. menu and click
- In Admin Studio, click Resources > APIs.
Click an API name or the action on the right side of the row to expand the row, for example, /cases or Get Cases.
You can list parameters and view the JSON data model for each resource, and identify possible response messages.
The Pega API also allows you to directly test any API in the help by clicking thebutton. After the Pega API passes an initial authentication challenge, tests display the actual request URL, response body, response code, and response headers.
For more information about the Pega API, including how to secure it, see the Pega API.
Developer best practices
When developing client applications that are powered by any Pega API, follow these guidelines:
- Make it easy for users to specify a host system, for example:
- Prompt users at installation or first use to enter host information for their application.
- Provide a Gear icon that opens a configuration details screen in which the user can enter the system host name.
- Secure connections – Enable TLS to secure connections to the Pega API from a mobile or web application.
- Authenticate users
- Provide a login screen that authenticates users with a mobile or web application through the authenticate API by using their application credentials.
- Transmit user credentials by using basic authentication for every API call.
- Parse messages – Create and parse JSON request and response messages, respectively.
In addition, mobile and client application developers should be familiar with the Pega application data model to correctly format requests and understand responses from the Pega API.
Cross-origin resource sharing (CORS)
Use cross-origin resource sharing settings in Pega Platform to control and secure the Pega API services that are embedded in your web or mobile client application. Configure these settings to permit Pega API access across domains that you trust by using the headers that you specify. You can also control the time period between preflight requests.
Interaction between web browser and Pega Platform application server when remote Pega API services are accessed
For more information, see Configuring Cross-Origin Resource Sharing (CORS) for the Pega API.
The following examples show some ways that the Pega API can be used for your application. It is expected that multiple Pega API services are used together as part of a single process or as part of multiple business application processes. In particular, client applications should call a Pega API service to get a list of available cases, data, or assignments, and then make subsequent API calls to obtain further details or to make updates.
City services mobile app
The city services mobile app allows city residents to report issues such as potholes, graffiti, or damaged signs. For example: As you drive through the city, you encounter a big pothole in the street. You pull over, pick up your phone, open the app, and report the pothole.
Submitting and viewing a report:
- Log in to app (call the Pega API GET /authenticate).
- View the list of possible issues to report (call the Pega API GET /casetypes).
- View the list of city regions (call the Pega API GET /data/D_CityRegionList).
- Select an issue and region.
- Submit the report (call the Pega API POST /cases).
- View all submitted reports (call Pega API GET/cases).
- Open a specific report to view details (call Pega API GET/cases/ID).
Problem report workflow for city services mobile app
Time and expenses mobile app (manager)
As a manager using a mobile time and expenses mobile app, you want to see a list of your employees' expense reports and the time sheets that are currently assigned to you so that you can approve or reject them.
Manager approval workflow for time and expenses mobile app
Time and expenses mobile app (employee)
As an employee using a mobile time and expense app, you want to be able to submit time and expense reports and view their status.
Submitting a report:
- Log in to the mobile VPN.
- Open the Time and Expenses app (call the Pega API GET /casetypes).
- Select an expense report from the list.
- Complete the expense report.
- Submit the expense report (call the Pega API POST /cases).
Viewing case status:
- Log in to the mobile VPN.
- Open the Time and Expenses app and click the Status tab (call Pega API GET /cases).
- View any available expense reports.
- Select a specific case for more details (call Pega API GET /cases/ID).
Employee workflow for submitting expense reports and viewing status