More about Service REST rules
Invoking a service rule
To send a request to an REST service rule, use the URL of the
PRRestService
servlet. Append the three-part key to the rule to the URL.
Use the following syntax:
http://servername:portnumber/contextroot/PRRestService/packageName/className/URItemplateFor example:
http://MyServer:8080/prweb/PRRestService/SampleREST/Phonebook/AddContactService REST rules that are created as of 8.1 cannot be invoked with partial resource URIs.
URI template
Use the Service tab to modify the variable components of a URI template.
For information about URI templates, see Distinct URI specification for service REST rules.
For Service REST rules that were created before Pega 8.1, the URI template field is instead a resource path that you can append to the URL.
Authentication
When the service runs as an authenticated user, the external application sending the
request must include the username and password of an Operator ID in the request. The
external application can send these values either in an HTTP header, or appended to the URL
as name/value pairs for the parameters
UserIdentifier
and
Password. The value of the password must be base64-encoded.
Stateful sessions
When the session state in a service package is set to
Stateful, the
service returns a cookie in the response with the Set-Cookie HTTP header. The cookie
contains the Requestor ID of the requestor that processed the first request, with the prefix
"PegaRULES." For another request to access the same session data, the external application
must include the PegaRULES cookie in the header of that request.
Custom cookies and stateful sessions
A response can contain only one Set-Cookie header. If a Set-Cookie is set in the data mapping on the Response tab, the Pega Platform does not set the PegaRULES cookie for you. So if the services run in a stateful session and you need to return custom cookies, your rules are also responsible for constructing the PegaRULES cookie.
Create the cookie string by concatenating all the cookies to be sent, including the
PegaRULES cookie, into one string. The value of the PegaRULES cookie must be the requestor
ID. For example:
PegaRULES=H40F706525721982DE3C8530D6DC64FCD.
Get the value of the requestor ID from the
pzRequestorId
property on
the
pxRequestor
page, which is always present on the clipboard. This can be
accomplished either by having the service activity set a clipboard property, or through a
Rule-Utility-Function. Then, use the Response tab to configure a
Set-Cookie
header that contains the string with the values of all the
cookies.
OpenAPI
Use the OpenAPI tab to view the pre-generated YAML code that describes your REST service and shows how it will look in your Swagger document. Before you add the pre-generated YAML to your Swagger page, you must add the following additional details:
- The model for each HTTP return code.
- If your REST service responds to a POST, PUT or DELETE method, specify the model of the request BODY expected by your service.
After you add these details to your YAML code, select Swagger to view and test your service using the Swagger page.
Performance logging
You can collect performance statistics about the resources used by a service in a Comma-Separated-Values (CSV) file, accessed from the Log menu. See Performance tool — Statistics for services in the SERVICES-PAL log.
You can trace the operation of a Service REST rule and the service activity it calls. See Tracing services.