If you have worked through the SOAP module, you already know the pattern. Service rule, connector rule, error handling. REST follows the same structure – just with a different protocol, a lighter message format and a lot more flexibility.
Before building anything, it helps to understand what REST actually is and how Pega works with it.
What REST Is?
REST stands for Representational State Transfer. It is not a protocol – it is an architectural style. Two key characteristics define it.
First, it is stateless. Each service call is independent. No session is maintained between requests. You call a service, you get a response, the transaction ends. This is different from, say, a browser session where state is maintained throughout.
Second, it is lightweight. Especially when paired with JSON as the message format, REST messages are significantly smaller and faster to process than SOAP with XML.
HTTP Methods
REST uses standard HTTP methods to perform different types of operations.
GET retrieves data. No request body – you pass parameters either through the resource path or query strings. If you want to get customer details, you use GET. Think of it like a data page query.
POST creates a resource. It has a request body, which is where you pass the data needed to create something – a new case, a new record, whatever the API requires.
PUT updates an existing resource. Similar to POST but semantically means you are replacing or updating something that already exists.
DELETE removes a resource. Like GET, no request body – you identify what to delete through the path or query string.
PATCH does a partial update – only updating specific fields rather than the whole resource. Pega added support for this in more recent versions, likely because external systems using PATCH were previously unsupported.
In practice, GET and POST are the methods you will use most often in Pega projects.
The REST URI Structure
A REST URI identifies the resource you are accessing. In Pega, when you expose a service REST, the URI follows a predictable structure – the host and port, followed by Pega’s base resource path, followed by the API name and version, followed by the actual resource you are exposing.
You can also parameterise the resource path. Getting a specific customer’s details might look like /customer/prem rather than passing an ID as a query string. Both approaches work – the choice is yours as the service designer.
JSON Message Format
REST supports both XML and JSON, but JSON is the preferred and far more common choice in modern integrations.
JSON structures map naturally to Pega properties. A simple name-value pair maps to a single value property. An object in curly braces maps to a page property. An array in square brackets maps to a page list property.
When you use the Connect REST wizard in Pega and provide sample request and response JSON, Pega automatically creates the corresponding data classes and properties for you. This is one of the reasons Connect REST development moves quickly once you have the API details from the provider.
Why REST Over SOAP
The shift away from SOAP has been happening for years and is now essentially complete for new development. REST messages are lighter, JSON is simpler to work with than XML, REST supports multiple HTTP methods while SOAP only supports POST, and REST URIs are easier to document and consume than WSDL files.
SOAP still exists in legacy systems and you will encounter it on older projects. But any new integration work you do will almost certainly be REST.
Watch the Full Walkthrough
In the video below I cover all the REST fundamentals in depth – URI construction, HTTP methods, JSON structure mapping to Pega properties, and why REST has become the standard for modern integrations.
This module covers service REST, Connect REST and error handling across separate videos. This one sets the foundation for everything that follows.
