External API design

External engineering teams often build or adapt APIs so Actions can retrieve data, update records, or initiate workflows. These guidelines describe how to design APIs that integrate smoothly with Actions and deliver consistent, reliable behavior in production environments.

Core protocol and data format

Actions communicate with your external APIs using standard HTTP requests. The following guidelines describe the formats and conventions Actions expect or work best with.

HTTPS

Actions call external APIs over standard HTTPS. Endpoints must be reachable over the internet so Actions can send requests.

Supported data formats

Actions can work with responses returned in supported data formats, including JSON, XML, and URL-encoded data.

In practice, Actions commonly send and receive JSON payloads. When using JSON, include standard HTTP headers that clearly identify the response format:

These headers help ensure consistent parsing and predictable behavior when JSON is used.

Request and response structure

While Actions can work with a variety of JSON structures, the following practices help ensure stable and predictable integrations:

• Deterministic responses: The same request should return responses with consistent field names and types.
• Stable schema: When introducing changes to your API, add fields rather than removing or renaming them.
• Clear structure: Avoid unnecessarily deep or ambiguous nesting, which can make Action output mapping harder.

Timestamps

If your API returns timestamps, using a standard format such as ISO-8601 UTC is recommended. For example: 2025-12-11T16:40:00Z. This format is widely supported across tools and makes it easier for Actions to pass timestamp data to downstream systems.

Authentication

Actions support several authentication methods when calling your external APIs. This section outlines the authentication models available and the typical expectations for each approach.

Static bearer tokens (server-to-server)

Actions must include a static bearer token when calling your API, using the standard HTTP header: Authorization: Bearer.

• It’s best to use scoped, long-lived tokens or rotate them safely.
• This model is appropriate for simple, system-level integrations that do not require per-user authentication.

OAuth 2.0 authorization code (per-user access)

If your API needs to act on behalf of authenticated users, Actions can complete an OAuth 2.0 authorization code flow.

• Your system must provide:
  • Authorization URL
  • Token URL
  • Proof Key for Code Exchange (PKCE) or standard authorization code support
  • Refresh tokens
• Recommendations:
  • Support PKCE where possible
  • Provide refresh tokens for long-running sessions
  • Use short-lived access tokens for added security

API behavior

The following practices reflect widely adopted REST API patterns and can help ensure predictable and reliable integrations when Actions call your external APIs.

REST-style endpoints

Standard HTTP methods should follow widely adopted REST semantics:

Versioning

Using versioned endpoints helps maintain long-term compatibility, especially as your API evolves. A common pattern is to include a version in the URL, for example:

• /api/v1/orders
• /api/v1/customers

Adding new fields over time maintains compatibility, while breaking changes are typically introduced in a new version (v2, v3, etc.).

This approach provides stability for any client consuming your API, including Actions.

Pagination

Actions do not automatically retrieve additional pages of results. If an API response is paginated across multiple pages, Actions process only the data returned in a single request.

When building endpoints intended for use with Actions, ensure that each request returns all data required for the Action to complete, otherwise only the first page of a paginated response will be processed.

Idempotency

Designing APIs to be stateless and idempotent helps ensure reliable behavior when used with Actions. If the same request is sent multiple times (for example, due to retries after a network interruption), the operation should be processed only once and should not result in duplicate records or repeated side effects.

Actions do not support idempotency keys, so idempotent behavior must be handled through API design.

Error handling

When designing error responses, following common API conventions can make your API easier for automated systems (including Actions) to work with.

HTTP status codes

Using HTTP status codes consistently helps clients understand how to react:

• 2xx: Request succeeded
• 4xx: Request was invalid or unauthorized
• 5xx: Server encountered an unexpected error

Error responses

Providing predictable, machine-readable error responses makes it easier for clients to handle failures programmatically.

1
{
2
    "error": {
3
        "code": "INVALID_INPUT",
4
        "message": "Email format is invalid",
5
        "field": "email"
6
    }
7
}

Rate limits

When an API used with Actions returns a rate-limited response, the request is not retried. Actions process each request once, and a rate-limited response causes the Action to be marked as failed.

If your API applies rate limits, returning standard HTTP rate-limit responses (such as 429 Too Many Requests) can help clearly indicate that a request was rejected due to rate limiting. This information is useful for understanding and diagnosing Action failures, but retry or backoff behavior must be handled outside of Actions (for example, within the API itself).

Security

The following security practices are widely used across modern REST APIs and help ensure safe interactions when external systems call your API.

• Always use HTTPS to encrypt requests and responses in transit.
• Avoid exposing sensitive personally identifiable information (PII) in responses.
• Never include secrets (such as API keys or tokens) in error messages or logs.
• If your API requires IP allowlisting, provide static outbound IP ranges so external systems can be granted access without interruption.

Webhooks (not supported)

Actions do not support webhook-style endpoints and cannot receive incoming webhook requests.

Observability and debugging

In integrations that involve multiple systems, problems can originate in several places. Good observability, such as shared request IDs and consistent logging, helps teams quickly pinpoint whether an issue occurred in the client, the API, or downstream services.

Request ID correlation

Automated systems may include a request identifier in outbound calls, such as: X-Request-Id: .

Echoing this value in your response helps correlate related events across services. This practice is widely adopted in distributed systems and does not imply any specific implementation on the caller’s side.

Logging

When logging requests or responses, consider the following:

• Do not log full tokens, secrets, or sensitive user data.
• Log stable identifiers (such as resource IDs), timestamps, and any request IDs provided by the client.
• Ensure logs contain enough information to trace behavior without exposing sensitive data.

These are general logging recommendations suitable for any API integration.

Example endpoint

The following example illustrates common REST API patterns. It uses JSON for illustration purposes. XML and URL-encoded formats are also supported. Your API may return responses in other formats as long as they are predictable and documented.

POST /api/v1/orders
Authorization: Bearer {Token}
Content-Type: application/json
Accept: application/json

1
{
2
    "customer_id": "cus_123",
3
    "items": [{ "sku": "abc", "qty": 2 }]
4
}

1
{
2
    "id": "ord_789",
3
    "status": "created",
4
    "created_at": "2025-12-11T16:40:00Z"
5
}

1
{
2
    "error": {
3
        "code": "INVALID_SKU",
4
        "message": "Invalid SKU"
5
    }
6
}

See also

• Actions overview
• Action control
• Token configuration
• API overview
• Authentication