Exposing an application as a service
The two most common ways to expose your application as a service are either to use the Pega API or create a web service with the Service Wizard.
Conceptually, these two options work the same way by making a request to a URL, and then receiving a response. The difference is in how you communicate with the service.
Pega APIs communicate in more generic terms about the resources of your application, such as cases. For example, you use Pega APIs if an external application requires a list of case attachments, or needs to retrieve case details and make subsequent calls to update. You can use multiple Pega API services as part of single or multiple application processes.
Pega API provides a standard set of services that includes new case creation, assignment processing, and access to data pages. These built-in REST/JSON services enable rapid implementation of Pega-powered mobile and client applications.
You can call any of the Pega API services by using standard HTTP methods (for example, GET, POST, or PUT). To see details of the request and response data requirements, view the Pega API resources page in Dev Studio or App Studio:
- In Dev Studio, click the Resources menu, and then select Pega API.
- In App Studio, click Channels, and select API.
The following resources are available through Pega API:
|Assignment API||Obtain a list of assignments for a user, obtain the details of any specific assignment, and perform an assignment action.|
|Authenticate API||Verify user credentials.|
|Cases API||Obtain a list of cases for a user, create a new case, obtain case details, and update a specific case.|
|Casetypes API||Obtain a list of case types for the authenticated user.|
|Data API||Facilitate the process of obtaining the contents of a data page and obtaining the metadata for a specific data page.|
|Docs API||Access complete documentation for Pega API.|
Note: For more information about Pega API, see Integrating with Pega APIs and services. Documentation is also available in the JSON format in the Docs API (GET/docs).
Consider the use case of an application that allows electric vehicle drivers to report issues with city-owned chargers. As users encounter an issue, they access the application and report the issue. A city employee then reviews the issue report for further action. The Pega API interactions include:
- Log in to the app by calling GET /authenticate.
- View the list of possible issues to report by calling GET /casetypes.
- View the list of city regions by calling GET /data/D_CityRegionList.
- Select an issue and a city region.
- Submit the report by calling POST /cases.
- View all submitted reports by calling GET /cases.
- Open a specific report to view details by calling GET /cases/ID.
Because Pega APIs are resource-oriented and not action-oriented, if you need to perform a particular action such as having an external caller notify a Pega Platform application that a specific event has occurred, you need to build or use a custom API using the Service Wizard. When you use custom APIs, you can define the requests and responses more specifically by using the actual data model of your application. You can create custom REST/JSON services for external systems to integrate with your Pega Platform applications to request, receive, send data, or invoke an action.
For example, an external application needs to access insurance policy details and then notify your application to process a specific event. You expose a REST service with the required parameters and provide a response with those policy details to the external application.
Tip: Before selecting which API you need, familiarize yourself with the Pega Platform™ data model so that you can correctly format requests and understand responses from Pega API.
Access the Service Wizard by clicking Configure > Integration > Services > Service Wizard. The Service Wizard generates rules and data types for services that perform one of the following tasks:
|Create and manage work||Create new work items or perform actions on a work object such as a flow action.|
|Invoke existing activity rules||Call an activity and select service parameters.|
|Process input or output data||Map data to or from the clipboard.|
The Service Wizard completes each of these tasks through five general steps, for which the Service Wizard displays a sequence of forms to fill out that define the appropriate service rules and the supporting data types. Some service purposes may contain more substeps than others because of the nature of their configuration. When you finish, the Service Wizard displays the values that you specified, which you can then review and modify before creating the service rules.
In the following image, click the + icons to learn more about the five general steps of the Service Wizard.
Check your knowledge with the following interaction.