Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Connect an external read and publish a scoped business API
This tutorial teaches two connected but distinct contracts: an exact published Integration for a business lookup, and a managed API registry/key for an exposed read-only rule. A published Integration is not automatically a public machine API. The rule used for the public teaching route must have its own real current source/input/disclosure contract.
Start with the leave data/rules foundation, an owner-admitted synthetic external service and the identity/permissions lab. Nadia is the author, while credential, provider and runtime owners retain their actual authority. Follow consultant Integration workflows, connectors and API management for detailed field/error tables.
| Object | Identity to retain | Distinct question |
|---|---|---|
| Connected system | Actual system/version and credential owner | Where/how may the platform connect? |
| Integration draft/version | Actual draft, saved request state and published version | What exact business call is authored and admitted? |
| Execution/fixture | Exact attempt and its safe provenance | What was actually observed, and what remains uncertain? |
| Exposed business rule | Key/version semantics and declared inputs/result | Which reviewed computation/read may a consumer invoke? |
| Published API | Public path and server-derived apiKey | Which route resolves to that exposed rule? |
| Managed key | Credential metadata plus protected show-once secret | Which workspace/routes/rate/expiry may this machine use? |
All requests are documentation examples. No external call, live test, key issue, runtime or provider qualification was executed as part of this manual program. Use real IDs and secrets only through the admitted environment/owner paths; none are embedded here.
Milestone 1 — Prepare a deliberately narrow external contract
Scenario and inputs. The service owner has admitted a synthetic employee source, its transport address, credential owner and read operation. Nadia’s goal is to reuse one nonmutating business lookup. No .example URL or placeholder secret in documentation is a runnable provider endpoint.
Procedure. 1. Record the real connected system and immutable connection version, source owner and allowed synthetic employee identifier. 2. Choose the exact operation and inspect whether it is truly nonmutating under the service contract, not merely named GET. 3. Write the minimal required input/output worksheet and disclosure classification. 4. Confirm Nadia’s current connector/system/Integration permissions and any allowed provider-test budget. 5. Keep actual credentials in the admitted owner-managed store; do not copy them into mapping examples or output fixtures.
Expected result. The integration has a bounded business purpose and an accountable external owner before discovery/import or any execution. The user-facing application will receive only its admitted output fields, not the service’s entire personnel record.
Failure and recovery. If address, credentials or provider authority are missing, preserve the concrete dependency and continue authoring the local contract. Do not probe private destinations, borrow another identity or use an unrestricted account to make the tutorial advance.
Sources. ConnectorController.java, IntegrationController.java.
Milestone 2 — Review discovery or import without automatic publication
Scenario and inputs. Nadia receives an approved OpenAPI description or discovers an operation through the existing connected-system flow. The document and selected service address have explicit owner custody. Import should create reviewed drafts, not silently publish every operation.
Procedure. 1. Use the actual supported discovery/import route for that transport. For OpenAPI, inspect /api/connected-systems/import-openapi/preview and its content/url contract. 2. Review proposed operations, addresses, defaults and unsupported findings. 3. Select only the employee READ operation and retain the preview fingerprint. 4. Apply that selection through /import-openapi/apply with the same source/fingerprint and explicit changed-operation decisions where needed. 5. Open the resulting actual drafts and inspect their state before any test or publication.
Expected result. The selected drafts exist with traceable source identity. A successful preview/apply does not prove credentials, output mapping, provider availability or published-runtime compatibility; those remain separate decisions.
Failure and recovery. If the source changes between preview and apply, repeat the actual review rather than reusing an old fingerprint. A denied destination or unsupported operation is a real limitation; do not add a proxy, change an allowlist or fabricate provider output as a workaround.
Sources. OpenApiImportController.java, OpenApiImportController.java.
Milestone 3 — Author typed inputs and a minimal output shape
Scenario and inputs. The selected employee operation is now an actual Integration draft. Nadia has its ID and connection identity. The application needs an explicit employee selector and a small output shape; arbitrary returned JSON or server-private transport metadata must not leak into public consumers.
Procedure. 1. Declare the actual typed inputs and required/default semantics in the Integration editor. 2. Bind them to supported request parameters/body through the real requestBindings/mapping contract. 3. Define the authoritative response output shape and selected fields; distinguish scalar/single-record/collection before choosing an interface consumer. 4. Inspect /drafts/{draftId}/request-validation findings and save with the actual expectedUpdatedAt token required by this surface. 5. Keep retry/paging metadata aligned with the actual operation and do not insert reserved internal provenance fields into options.
Expected result. The saved draft’s input/output contract can be reviewed without executing a provider or inferring fields from a sample alone. The selected shape is the one later publication and consumers must agree with.
Failure and recovery. If a required selector has no valid source/default or output shape is unknown, keep the consumer unavailable and correct the real contract. Do not broaden output to ANY, hide validation messages or infer success merely because a user-entered object parses as JSON.
Sources. IntegrationController.java, IntegrationController.java.
Milestone 4 — Test the exact draft and publish an immutable Integration
Scenario and inputs. The owner has explicitly admitted the selected synthetic provider test. Nadia must retain evidence tied to the actual saved request state. This document does not itself execute that test or qualify the provider.
Procedure. 1. Read the draft’s actual test-readiness and confirmation preparation. 2. Honor any server-authored live execution challenge; a local Boolean or new idempotency string is not a substitute. 3. Execute only the allowed test, retaining the real execution ID, request revision/fingerprint, input and sanitized result. 4. Save the supported deterministic fixture using that exact provenance. 5. Publish /drafts/{draftId}/publish-version with the actual selected fixtureId when required, then read its immutable version/contract. 6. Use its exact versioned execution route for future Integration calls, never the direct connector proxy.
Expected result. The Integration’s published version is coherent with the reviewed authored/tested state. Its fixture can be reused only within the actual fixture contract; it does not prove every future live call or authorize broader application inputs.
Failure and recovery. A changed draft/connection requires re-evaluating the changed request evidence. If the original test result is uncertain, inspect/reconcile the exact execution before any new attempt. Do not forge a fixture, replay a possibly mutating call or claim a source inspection as provider execution.
Sources. IntegrationController.java, IntegrationController.java.
Milestone 5 — Expose a separately reviewed read-only business rule
Scenario and inputs. Nadia wants an external machine consumer to search admitted leave data. This example uses a real exposed leave-search rule; it does not claim every published Integration is directly addressable as a managed API or that a machine key can complete a human task.
Procedure. 1. Select an actual read-only business rule with a reviewed declared input/output contract and native source/disclosure authorization. 2. Publish/expose it through its supported rule lifecycle. 3. As an actor with API-management permission and workspace ADMIN, register the path through POST /api/api-management/published-apis using the complete body below. 4. Retain the server-returned apiKey and inspect the native OpenAPI document for the actual declared request schema. 5. Keep Integration publication and this separate registry mapping traceable; do not confuse their IDs or version semantics.
{
"name": "Leave search",
"description": "Read-only teaching API",
"path": "hr/leave-search",
"ruleKey": "leave-search"
}
Expected result. The registry binds a strict public path to an eligible exposed rule in one workspace. The path-derived apiKey is a machine scope identifier, not a credential or arbitrary human label. No key has yet been issued to a consumer.
Failure and recovery. An unexposed/unavailable target, invalid path or conflicting path-derived slug must be resolved through the actual rule/registry owner. Do not widen access or expose a mutating rule whose participant/intent requirements cannot be safely satisfied by the machine caller.
Sources. AdminPublishedApiController.java, PublishedApiDispatchController.java.
Milestone 6 — Issue a narrow managed key and call with declared inputs
Scenario and inputs. The actual registry returned hr-leave-search for the chosen training path. The authorized credential owner will retain the show-once secret. This is a machine credential with a pinned workspace, not a user session or the rule Web-API key family.
Procedure. 1. Issue a managed key with scope API_KEYS and only the actual path-derived apiKey, plus deliberate rate/expiry policy. 2. Store the real returned secret only in the protected credential owner’s store. 3. Call POST /api/pub/hr/leave-search with the supported Bearer or X-Api-Key header and the dispatch body below. 4. Interpret the actual RuleExecutionResult under the current exposed rule’s input/version semantics; do not assume generic data/success fields. 5. Confirm a caller-supplied workspace header cannot redirect the same key into another workspace.
{
"name": "Leave search consumer",
"scope": "API_KEYS",
"apiKeys": [
"hr-leave-search"
],
"callsPerMinute": 60
}
Complete dispatch-body example for a rule declaring these inputs:
{
"inputs": {
"employeeId": "actual-admitted-employee-id",
"status": "PENDING"
}
}
Expected result. The filter pins workspace and enforces key validity/rate policy; dispatch enforces covered API path, active registry target, eligible exposed rule and input contract. A missing required input remains a rule-input refusal rather than an empty query result.
Failure and recovery. For out-of-scope, invalid/revoked/expired or suspended targets, correct the exact credential/registry owner decision. Never retry with a borrowed secret, log the bearer value, issue ALL_PUBLISHED for convenience or treat a 503limiter-storage failure as permission to skip limits.
Sources. AdminManagedApiKeyController.java, PublishedApiDispatchController.java.
Milestone 7 — Operate changes and uncertain outcomes without broadening authority
Scenario and inputs. The consumer is integrated and the source may change over time. The operator needs a safe story for lower rate limits, narrower scopes, secret rotation, API suspension and log gaps. Published versions and original external execution evidence remain part of the application’s history.
Procedure. 1. Narrow supported key policy through PATCH without assuming it rotates the secret; use the actual separate rotate endpoint when exposure requires a successor/revoked predecessor. 2. Suspend a route deliberately when the owning business API must stop. 3. Review source/Integration diffs and consumer impacts before publishing a replacement. 4. Correlate failed calls using sanitized persisted request logs and safe execution IDs; treat same-node SSE as a bounded live aid. 5. For any effectful native operation, reconcile its original intent/receipt rather than replaying it after a client disconnect. 6. Retain current credential/publication audit and source-custody constraints.
Expected result. The operator can distinguish policy edit, secret replacement, registry state, source version and original outcome knowledge. Reusing the same public path after deletion can regrant access to keys still naming its apiKey, so removal/republication needs deliberate scope review.
Failure and recovery. A concurrent key update, stale Integration draft, unsupported source or unknown remote outcome requires its own concrete recovery. Do not delete audit history, broaden credentials, disable checks or mark an uncertain provider effect successful just to restore a green dashboard.
Sources. AdminManagedApiKeyController.java, AdminApiLogStreamController.java, ConnectorController.java.
What a complete learning result includes
Keep the actual source/connection contract, saved draft and immutable Integration version, fixture/execution provenance, exposed rule input/result contract, registry apiKey and protected managed-key metadata. A list of screenshots or a connection ping alone cannot establish the connected business behavior. The reader should be able to explain at least one normal result and the exact response to missing input, denied scope, suspended API, stale publication and uncertain external outcome.
Continue with governed AI and agents only when the actual data/provider disclosure policy admits that separate use. An employee field readable by a human or callable machine API is not automatically authorized for embeddings, model prompts, reranking or retained agent memory. Use operate and deploy for environment-specific deployment and credential handoff; never export plaintext secrets in an application example.