The REST integration interface in Pega Platform supports interactions with external systems through Web services. Service REST rules expose the REST APIs that another application can call to invoke an action or to retrieve data from Pega Platform.

Pega API

Pega Platform provides APIs that come with an extensive set of services that you can use to manage and interact with all aspects of your application, such as cases and assignments. You can use multiple Pega API services as part of a single process or as part of multiple business application processes. For example, client applications can call a Pega API service to get a list of available cases, data, or assignments, and then make subsequent API calls to get further details or to make updates.

For more information, see Pega API services.

Building a new REST API

Sample scenario

Consider a scenario in which a healthcare application needs to access details of a patient from a Pega Platform application that is hosted on a separate environment.

In this case, you need to expose a REST service from the Pega Platform application with the GET REST method. This method fetches the details of the patient and provides the OpenAPI Specification (OAS) documentation that describes the input parameters and response structure. The healthcare application invokes the REST service by providing the specified parameters, and then retrieves the patient details.

Configuring a service package

Before you create a Service REST rule, create or identify the service package instance to which the service belongs. Each service belongs to a single service package.

1. Group the service rules that are designed to be developed, tested, and deployed together into a service package.
2. Define the processing mode, security scheme, and access for the services in the service package.
   • If the service package is unauthenticated, the access group that is specified on the service package is used for design time validation for dependency management and to execute the correct service rule at run time.
   • If the service package is authenticated, the access group is used for design time validation for dependency management and proper packaging and to check if the service exists at run time.

OAuth 2.0 is the recommended authentication scheme.

For more details, see Creating a service package.

Configuring the Service REST rule

For details on how to create a new Service REST rule, see Creating a Service REST rule.

When you select Swagger on the OpenAPI tab, the Server field lists the application alias URLs for the applications to which the logged-in user has access. By changing the value in the server list, you can test that API against another application to which you have access. Note that this action does not reload the OpenAPI in the context of that application. The Swagger that is shown is still in the context of the current application to which you are logged in. This method shows you the ways in which you can call this API and allows you to test against other applications easily.  

Viewing application-specific APIs

In the Application definition landing page, you configure the list of service packages that you want to view in Admin Studio, Dev Studio, and App Studio. When you list the service packages that contain REST services in your application rule, their OAS documentation is included in your application's OAS documentation.

For more information, see Best practices for generating OpenAPI Specification documentation and Viewing application-specific REST APIs.

General guidelines

1. Familiarize yourself with the Pega Platform data model so that you can correctly format requests and understand responses from the Pega API.
2. Follow best practices for generating accurate and complete OAS documentation in your application. For more information, see Best practices for generating OpenAPI Specification documentation.
3. Ensure that you have a robust exception handling in place.
4. Evaluate the API design for performance.
5. Ensure backward compatibility over versions by keeping required parameters and providing only new changes.
6. You can unit test the Service REST rules from the service rule, service package rule, Swagger UI, and external clients.
7. Provide specific, defined extension points while building the Service REST rules for the customers to extend our services for additional mapping from Pega Platform applications to maximize reuse. These specific extension points should be only the available rules; other implementation rules (and the Service REST rule itself) should be marked Final to ensure that they are easily updatable.

For details about monitoring Service REST rules, see Service REST monitoring.