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.
Actions interact with external APIs for every operation. The table below highlights which parts of an integration are required for compatibility and which are recommended to ensure consistent performance under automation, with links to relevant sections.
Actions communicate with your external APIs using standard HTTP requests. The following guidelines describe the formats and conventions Actions expect or work best with.
Actions call external APIs over standard HTTPS. Endpoints must be reachable over the internet so Actions can send requests.
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.
While Actions can work with a variety of JSON structures, the following practices help ensure stable and predictable integrations:
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.
Actions support several authentication methods when calling your external APIs. This section outlines the authentication models available and the typical expectations for each approach.
Actions must include a static bearer token when calling your API, using the standard HTTP header: Authorization: Bearer.
If your API needs to act on behalf of authenticated users, Actions can complete an OAuth 2.0 authorization code flow.
The following practices reflect widely adopted REST API patterns and can help ensure predictable and reliable integrations when Actions call your external APIs.
Standard HTTP methods should follow widely adopted REST semantics:
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/customersAdding 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.
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.
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.
When designing error responses, following common API conventions can make your API easier for automated systems (including Actions) to work with.
Using HTTP status codes consistently helps clients understand how to react:
5xx errors typically reflect temporary server-side issues where retrying the request may succeed. By contrast, 4xx errors indicate a problem with the request itself (such as invalid data or missing authorization), so resending the same request will produce the same result.Providing predictable, machine-readable error responses makes it easier for clients to handle failures programmatically.
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).
The following security practices are widely used across modern REST APIs and help ensure safe interactions when external systems call your API.
Actions do not support webhook-style endpoints and cannot receive incoming webhook requests.
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.
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.
When logging requests or responses, consider the following:
These are general logging recommendations suitable for any API integration.
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.
Explore complementary resources for building and managing Actions.