What does "Status: API" actually mean In pega "Activity" Rule?

Pega-as-a-Service Knowledge Share
, , , ,
1

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:

  1. Interface Name: This is a descriptive name for the “service” this activity provides. It’s used to group related APIs together in documentation.

  2. 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!

image
image333×252 5.56 KB

3 Likes
2

Spot on. We were actually discussing this exact idea with a colleague a couple of years ago. The recurring question was this: in traditional programming languages, you can mark a function as private, which prevents it from being used externally.

In Pega, we have something similar — rules can be marked as Internal, which triggers a guardrail warning if they’re invoked from another ruleset. On top of that, you can add a Parapets Studio restriction to block it entirely.

The problem is that every rule has to be explicitly marked as Internal. That’s tedious, and realistically, no one does it consistently in practice.

Curious what your view is on this. How would you solve it? Is there any existing automation that helps here?

1 Like
4

Excellent point, Ivan. The comparison to private vs. public modifiers in Java or C# is exactly how we should be thinking about rule visibility in Pega.

In my view, we haven’t seen a ‘silver bullet’ automation for this because the status of a rule (Internal vs. API) is fundamentally tied to the Developer’s Intent, which is hard for a tool to guess.

Here is how I see the ‘Human-in-the-loop’ solution working in place of automation:

  • The Compliance Burden: Ultimately, marking a rule as Internal or API is a part of the developer’s compliance checklist. If we don’t explicitly categorize our ‘heavy-hitter’ rules, we create technical debt for the next team.

  • Guardrail-Driven Discipline: Since using an Internal rule across rulesets triggers a guardrail warning, the ‘automation’ actually happens during the Review Phase.

  • Lead/Manager Intervention: During code reviews, Leads and Managers should be looking for these specific warnings. When a developer is forced to justify or remove a guardrail warning for using an internal rule, it naturally enforces the habit of checking the Rule Status.

While we might not have an automated ‘toggle,’ we can use Pega Checkers or custom PegaUnit tests to flag any rule in a ‘Service’ or ‘Integration’ ruleset that hasn’t been explicitly marked as API.

2 Likes