6.1 Open API Definitions: Building and Extending a Custom Connector

A custom connector is a wrapper around an existing REST (or SOAP) API that exposes that API's operations as standardized actions and triggers inside Power Apps, Power Automate, and Copilot Studio. Where a "standard" connector (SharePoint, Dataverse, Outlook) ships pre-built and maintained by Microsoft or a third party, a custom connector is one a developer builds against an API that has no existing connector — an internal line-of-business API, a partner's REST service, or an Azure resource. Functionally, a custom connector is just an OpenAPI (Swagger) definition plus a security scheme plus optional runtime policies, registered in a Power Platform environment so makers can use it exactly like any other connector: pick it from the connector list, create a connection, and drop its operations into a flow or app.

Three Ways to Start a Custom Connector

Power Platform gives you three entry points for creating a custom connector, all reachable from Power Apps > Data > Custom connectors > + New custom connector:

• Create from blank — start with nothing and manually define the host, operations, parameters, and responses through the wizard UI. This is the path used when no machine-readable API description exists yet.
• Import an OpenAPI file or URL — upload a Swagger 2.0 or OpenAPI 3.x JSON/YAML document, or point to a URL that serves one, and the wizard auto-populates the connector's operations from it.
• Import a Postman collection — upload an exported Postman collection (v1 format) and the wizard converts its requests into connector actions.

Whichever path you choose, every custom connector is configured through the same four-step wizard: General, Security, Definition, and Test. The General tab captures the connector's icon, description, host (the API's domain, e.g., api.contoso.com), base URL (the path prefix prepended to every operation, e.g., /v1), and scheme (HTTP or HTTPS). The Security tab sets the authentication type (covered in the next section). The Definition tab is where you build out actions and triggers — each one backed by a specific HTTP verb and path, request parameters, and a response schema. The Test tab lets you create a live connection and call an operation to confirm it works before makers rely on it.

Defining Actions from an OpenAPI Definition

When you build an action manually in the Definition tab, you provide:

• General — an operation ID (used programmatically and in flow step names), a summary (shown as the action's display name to makers), and a description.
• Request — the HTTP verb and URL path, plus parameters. You can import from sample, pasting a raw HTTP request so the wizard infers path, query, header, and body parameters automatically, or add each parameter manually and mark it required, set its location (path/query/header/body), and give it a default value.
• Response — again importable from a sample JSON payload, or defined manually as a schema. The response schema drives the dynamic content tokens makers see when they reference the action's output later in a flow (e.g., body('Create_Ticket')?['ticketId']).

Because a custom connector is fundamentally an OpenAPI document under the hood, everything you configure through the wizard UI is really editing that document's paths, parameters, and definitions/schemas sections. The Definition tab has a Swagger editor toggle that exposes the raw document directly.

Extending the OpenAPI Definition

The wizard's point-and-click UI does not expose every capability a connector supports — for that, PL-400 candidates need to know how to extend the Open API definition by hand-editing the raw Swagger, using Microsoft's x-ms-* extension properties:

Editing the raw definition is also how you fix issues the sample-based import cannot infer correctly — for example, marking an optional field as required: false, tightening an enum list so a parameter renders as a dropdown, or adding a missing description so the generated help text in Power Automate is meaningful. Because the Definition tab and the Swagger editor are two views of the same document, changes made in one are reflected in the other after saving, which makes it practical to build the bulk of an operation through the UI and then fine-tune the friendly-UI extensions by hand.

Defining Triggers: Polling vs. Webhook

Alongside actions, the Definition tab lets you define triggers — the operations that start a flow rather than run inside one. A custom connector supports two trigger patterns, and PL-400 expects you to know when each applies:

• Polling triggers call the API's endpoint on a recurring schedule (the interval a maker sets when they add the trigger to a flow) to check whether new data exists. The underlying operation typically responds with HTTP 202 (Accepted) while there is nothing new and HTTP 200 (OK) with a payload once new data is available; the connector definition marks the operation x-ms-trigger: "poll" and specifies how to detect "new" records (for example, a timestamp or sequence header). Polling is simple to implement against almost any REST API, but it introduces latency bounded by the polling interval and consumes an API call on every poll, whether or not new data exists.
• Webhook (push) triggers rely on the external API calling back into Power Automate the moment an event happens, instead of Power Automate repeatedly asking. Implementing one requires the connector to define a subscribe operation (registers a callback URL with the external service when a maker turns the trigger on) and an unsubscribe operation (deregisters that callback URL when the flow is turned off or deleted), marked x-ms-trigger: "single" with x-ms-notification-content describing the payload the webhook delivers. Webhook triggers are near-real-time and far cheaper on API calls, but they require the backing API to support registering callbacks in the first place.

Because webhook triggers depend on the target API supporting subscriptions, polling remains the fallback — and often the only option — for APIs that expose no callback mechanism.