What does “Status: API” actually mean?
When you change a rule’s status to API, you are marking it as a “Public Interface.” This tells other teams they can safely build on top of it. It also cleans up your guardrail reports by removing warnings associated with using internal or non-public rules.
Here is the breakdown of why you would use it:
-
Contractual Promise: By marking an activity as an API, you are telling other developers: “This activity is safe to call. I won’t change its parameters or core behavior without a very good reason.”
-
Documentation & Search: It makes the rule easier to find when people are looking for reusable “services” within your application.
-
Upgrade Safety: Pega uses this internally. If you use a Pega-provided activity marked as “API,” Pega guarantees (as much as possible) that it won’t break during an upgrade.
-
Encapsulation: It distinguishes between “Internal Only” activities (which might change frequently) and “External Facing” activities.
The Key Fields in that Dialog
When you select API, you’ll notice a couple of other fields become relevant:
-
Interface Name: This is a descriptive name for the “service” this activity provides. It’s used to group related APIs together in documentation.
-
Base Rule (Checkbox): If you check this, you are indicating that this is the primary definition of the API.
When should you use it?
We should set an activity to API status if:
-
We are building a reusable component that other teams in your company will call.
-
The activity is the entry point for an external system (like a REST service calling this activity).
-
Comparison: API vs. Template vs. (Blank)
| Status | Meaning |
|---|---|
| (Blank) | A standard rule. No special promises made about its future stability. |
| API | A stable, public interface meant for reuse across different modules. |
| Template | A “starter” rule. It’s meant to be saved-as into a different class and then specialized. |
Pro-tip: If we are just building a quick activity for a single UI button inside your own case type, leave the status blank. Only use API for the heavy hitters that are meant to be shared!
