.png)
Amazon API Gateway Integration Guide
Connect Amazon API Gateway REST, HTTP, and callback endpoints with enterprise workflows, applications, and backend services using Martini.
Amazon API Gateway integration options at a glance
Amazon API Gateway supports REST APIs, HTTP APIs, and WebSocket APIs for publishing, securing, routing, and monitoring API traffic. Martini can consume API Gateway REST or HTTP endpoints using API keys, bearer tokens, JWTs, Cognito-issued tokens, or other configured authorization methods. API Gateway can also expose HTTPS endpoints that receive webhook-style callbacks and route them to Martini or another backend. For the reverse direction, API Gateway can route requests to a Martini REST API. Binary payloads are supported when configured, while asynchronous processing, file storage, SOAP handling, and database access remain responsibilities of downstream services or Martini workflows.
| Integration point | Supported by Amazon API Gateway? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | REST APIs expose resources, methods, integrations, authorizers, stages, and deployments for synchronous enterprise operations and API façades. | Martini can consume API Gateway REST endpoints, map request and response payloads, expose its own REST API behind API Gateway, and orchestrate downstream calls. |
| HTTP APIs | Yes | HTTP APIs provide a lower-overhead route and integration model for Lambda and HTTP backends, with JWT or Lambda authorization options. | Martini can call HTTP API endpoints and can serve as an HTTP integration target behind API Gateway. |
| WebSocket APIs | Yes | WebSocket APIs support persistent, bidirectional communication organized around routes and connection events. | Martini can participate through available HTTP or application-level endpoints where appropriate, but the supplied Martini materials do not document a dedicated API Gateway WebSocket connector. |
| Webhooks and inbound callbacks | Limited | API Gateway can expose HTTPS endpoints that receive callbacks from external systems and route them to Lambda, HTTP services, or Martini. | Martini can expose an API or workflow endpoint for the callback, validate and transform the request, and process it asynchronously when the design requires. |
| SOAP proxying | Limited | REST or HTTP APIs can forward HTTP traffic to an external SOAP endpoint, but API Gateway does not provide WSDL or SOAP-native operation management. | Martini can consume SOAP services, transform XML and SOAP payloads, and handle SOAP faults when SOAP processing belongs in the workflow. |
| Binary payloads and file transfer | Limited | API Gateway can transmit binary request and response payloads when binary media types and proxy handling are configured; it has no native attachment repository. | Martini can validate and transform supported payloads, while larger files can be handled through a backend such as Amazon S3 and passed as references. |
| Authentication and authorization | Yes | API Gateway supports IAM authorization, API keys and usage plans, Lambda authorizers, Cognito user pool authorizers, JWT authorizers for HTTP APIs, resource policies, and mutual TLS configurations. | Martini can supply configured API keys, bearer tokens, JWTs, or other required credentials and store sensitive values in environment configuration or secrets. IAM SigV4 may require appropriate signing support or custom implementation. |
| Asynchronous routing | Limited | API Gateway can route requests to Lambda, Amazon SQS, AWS Step Functions, or HTTP backends, but does not provide a universal bulk or long-running job model. | Martini can submit requests, process status or result APIs, receive callbacks where available, and implement workflow-level retries and idempotency. |
How Amazon API Gateway exposes data and business events
Amazon API Gateway REST APIs
API Gateway REST APIs provide managed resources and methods with integrations, authorization, stages, deployments, request handling, and response controls. They are the primary option for exposing or consuming governed synchronous enterprise APIs.
Martini implementation pattern
Martini consumes the deployed REST endpoint with the configured authorization values, or exposes a Martini REST API that API Gateway routes to through an HTTP integration. A workflow validates the request, maps the payload, invokes downstream systems, and returns a controlled response.
Implementation sequence
Amazon API Gateway HTTP APIs
HTTP APIs provide a lower-overhead API model with routes, integrations, stages, and authorization options such as JWT or Lambda authorizers. They can route requests to Lambda functions, HTTP services, or Martini APIs.
Martini implementation pattern
Martini calls the HTTP API using its REST API consumption capabilities or receives requests from an HTTP API integration. Environment-specific endpoints and credentials remain outside workflow logic, while the workflow performs transformation, orchestration, and error handling.
Implementation sequence
Inbound callback endpoints
API Gateway can expose HTTPS endpoints that receive webhook-style callbacks from external applications. It can authenticate, throttle, and route the request, but it does not subscribe to external event feeds by itself.
Martini implementation pattern
The external application sends a callback to an API Gateway endpoint, which routes the request to a Martini API or another backend. Martini validates the inbound data, applies any event deduplication rule, transforms the payload, and starts the appropriate workflow.
Implementation sequence
Binary payloads
API Gateway can transmit binary request and response payloads when binary media types and proxy behavior are configured. It does not provide a native file repository or attachment object model.
Martini implementation pattern
Martini can receive or send a configured binary payload, inspect content type and encoding, and route file processing to a suitable backend. For larger files, the workflow should use an object-storage reference or job-control request rather than an unbounded synchronous body.
Implementation sequence
Asynchronous backend routing
API Gateway can route requests to Lambda, Amazon SQS, AWS Step Functions, or other asynchronous backends. Queueing, job tracking, retries, and completion semantics are provided by those services or application logic rather than API Gateway itself.
Martini implementation pattern
Martini submits a request or consumes a status or completion endpoint, then orchestrates the resulting enterprise synchronization. The workflow can preserve an idempotency key, poll a status resource, or receive a callback where the backend supports one.
Implementation sequence
Common Amazon API Gateway integration patterns
Pattern 1: Consume an API Gateway REST endpoint
When to use this pattern
Use this pattern when an AWS-hosted backend is published through API Gateway and Martini must retrieve or submit enterprise data. It is suitable for synchronous operations that require field mapping, validation, downstream enrichment, and controlled error handling.
Integration direction
Example Mapping
| Amazon API Gateway Field | Canonical Field | Target Field |
|---|---|---|
| requestId | correlationId | External reference |
| customerId | customerIdentifier | Account identifier |
| status | processStatus | Integration status |
Martini implementation pattern
Martini calls the API Gateway stage URL with the configured credential, validates the response, maps it to a canonical model, and invokes the target application. The workflow distinguishes authorization and validation failures from transient 429 or 5xx responses, using bounded retries for the latter and preserving correlation identifiers for support.
Martini capabilities used
- API consumption
- workflows
- data mapping
- business rules
- error handling
Pattern 2: Receive callbacks through API Gateway
When to use this pattern
Use this pattern when an external application sends webhook-style callbacks and requires a stable HTTPS endpoint with API Gateway authorization, throttling, or custom-domain controls. API Gateway receives and routes the request; the external system remains responsible for emitting the callback.
Integration direction
Example Mapping
| Amazon API Gateway Field | Canonical Field | Target Field |
|---|---|---|
| eventId | eventIdentifier | Deduplication key |
| eventType | eventName | Workflow route |
| payload | eventData | Canonical event body |
Martini implementation pattern
API Gateway routes the callback to a Martini API. Martini authenticates and validates the request, checks the event identifier for duplicates, maps the payload, applies event-specific business rules, and acknowledges only after the required processing or durable handoff succeeds.
Martini capabilities used
- exposing REST APIs
- receiving webhook-style requests
- data mapping
- validation
- workflows
- error handling
Pattern 3: Expose a Martini API behind API Gateway
When to use this pattern
Use this pattern when API Gateway should provide the public or private entry point, custom domain, AWS-level access controls, and throttling while Martini owns orchestration and downstream integration behavior.
Integration direction
Example Mapping
| Amazon API Gateway Field | Canonical Field | Target Field |
|---|---|---|
| Authorization | callerCredential | Martini authorization context |
| routeKey | operationName | Workflow selection |
| body | requestModel | Downstream request |
Martini implementation pattern
API Gateway forwards the request to a Martini REST API through an HTTP integration. Martini validates the caller context and body, selects a workflow, transforms the request for downstream services, and returns a consistent response model. Permanent failures are returned without retry, while transient downstream errors follow a bounded retry policy.
Martini capabilities used
- exposing REST APIs
- workflow orchestration
- API security
- mapping and transformation
- business rules
- error handling
Pattern 4: Process an asynchronous API Gateway request
When to use this pattern
Use this pattern when API Gateway routes a request to Lambda, Amazon SQS, AWS Step Functions, or another asynchronous backend and the enterprise process must track completion separately from request acceptance.
Integration direction
Example Mapping
| Amazon API Gateway Field | Canonical Field | Target Field |
|---|---|---|
| requestId | correlationId | Job reference |
| idempotencyKey | deduplicationKey | Backend request key |
| resultLocation | completionReference | Enterprise status or file reference |
Martini implementation pattern
Martini submits or consumes the asynchronous request, stores the correlation and idempotency values, and polls a status API or processes a completion callback when available. The workflow maps the completed result to the enterprise target and prevents duplicate writes when retries or repeated callbacks occur.
Martini capabilities used
- workflows
- API consumption
- scheduling
- data mapping
- business rules
- error handling
Applications commonly integrated with Amazon API Gateway
Amazon API Gateway commonly acts as a managed API entry point between named enterprise applications, AWS services, and integration workflows. These relationships do not imply application-specific native connectors in API Gateway; the adjacent application normally communicates through its own APIs or callbacks, while API Gateway provides routing, authorization, throttling, and endpoint management. Martini can orchestrate the resulting calls, normalize payloads, and apply reusable business rules.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Expose controlled business operations or route Salesforce-related requests to AWS-hosted services and downstream enterprise workflows. | Salesforce → Amazon API Gateway → Martini | Martini receives or sends normalized API payloads through an API Gateway endpoint, maps Salesforce fields to an internal model, applies validation and business rules, and handles transient failures or duplicate requests. |
| ServiceNow | Connect incident, request, asset, or automation workflows with AWS-hosted services and enterprise processing. | ServiceNow → Amazon API Gateway → Martini | API Gateway provides the managed HTTPS entry point or routes requests to a backend, while Martini validates ServiceNow payloads, orchestrates downstream calls, and records correlation and error information. |
| Jira | Support governed issue and project synchronization between Jira-related workflows, AWS services, and enterprise applications. | Jira → Amazon API Gateway → Martini | Martini consumes or exposes API requests through API Gateway, transforms issue fields into a canonical model, and routes create, update, or notification flows with retry controls. |
| Shopify | Receive storefront, order, customer, or fulfillment callbacks and route them to AWS processing and enterprise systems. | Shopify → Amazon API Gateway → Martini | API Gateway receives the callback endpoint request, Martini validates the event and signature-related data supplied by the application, transforms the payload, and synchronizes the result with downstream systems. |
| Workday | Provide a controlled integration layer for worker and HR-related exchanges with AWS-hosted services and enterprise workflows. | Workday → Amazon API Gateway → Martini | Martini calls or receives Workday-related requests through an API Gateway route, applies canonical employee or worker mappings, and separates retryable transport failures from validation and authorization errors. |
| SAP S/4HANA | Provide a governed API façade or route business-process requests between SAP and AWS-hosted services. | SAP S/4HANA → Amazon API Gateway → Martini | API Gateway fronts the integration endpoint while Martini transforms SAP payloads, applies process rules, invokes downstream APIs, and preserves request identifiers for operational tracing. |
| Zendesk | Synchronize tickets, users, and support events with AWS-hosted processing or downstream enterprise applications. | Zendesk → Amazon API Gateway → Martini | Martini receives callback-style requests through API Gateway or calls an API Gateway endpoint, maps ticket and user data, enforces idempotency, and routes failures for controlled retry. |
| Amazon S3 | Trigger file upload, download, processing, or metadata workflows backed by S3 while keeping API access controlled. | Amazon API Gateway → Martini → Amazon S3 | API Gateway carries authorization or job-control requests, Martini validates the request and orchestrates S3-related processing through configured backend APIs, and large payloads are handled as object references rather than unbounded synchronous transfers. |
How to build a Amazon API Gateway integration in Martini
Objective
Establish the API Gateway endpoint, stage, route, and authorization requirements before designing the workflow contract.
Instructions in Martini
- Identify whether the endpoint is a REST API or HTTP API and record the environment-specific stage URL.
- Configure API keys, bearer tokens, JWTs, Cognito tokens, or other required credentials in Martini environment configuration or secrets.
- Confirm whether IAM SigV4 signing, mutual TLS, resource policies, private routing, or allowlists are required.
Objective
Select whether Martini starts from an API request, an inbound callback, a schedule, or a downstream status check.
Instructions in Martini
- Use an API or webhook-style endpoint when API Gateway or an external application initiates the flow.
- Use a scheduled workflow for polling status or synchronizing data where no callback is available.
- Define the expected acknowledgement and timeout behavior for synchronous requests.
Objective
Obtain the API Gateway request or call the published endpoint while preserving the headers, route values, query parameters, and correlation identifiers needed for processing.
Instructions in Martini
- Capture request and response status codes, correlation headers, and backend error details.
- Preserve continuation tokens, job identifiers, or idempotency keys where the backend provides them.
- Treat API Gateway authorization, throttling, route, and backend errors as distinct failure classes.
Objective
Coordinate validation, enrichment, downstream calls, and response handling in a maintainable Martini workflow.
Instructions in Martini
- Route operations by method, route key, event type, or business status.
- Separate transport concerns from business processing and reusable downstream services.
- Apply bounded retries only to transient network, throttling, or server failures.
Objective
Convert API Gateway request and response structures into canonical and target application models.
Instructions in Martini
- Map JSON fields, headers, query values, and path parameters to the internal model.
- Handle XML or SOAP payloads in Martini when API Gateway is proxying an external SOAP service.
- Account for binary encoding, content types, and API Gateway proxy event structures when file payloads are used.
Objective
Validate required fields, enforce idempotency, and determine the correct target operation or response.
Instructions in Martini
- Reject invalid authentication, schema, and business data without retrying permanent failures.
- Use stable identifiers or idempotency keys to prevent duplicate creates and updates.
- Apply routing rules for synchronous, asynchronous, and callback-driven processing.
Common Amazon API Gateway data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| REST APIs | Represent managed REST interfaces with resources, methods, integrations, authorizers, stages, and deployments. | Martini APIs, enterprise applications, Lambda, HTTP services, and AWS services | Martini consumes the published endpoint or sits behind an API Gateway integration, mapping request and response contracts and applying workflow rules. |
| HTTP APIs | Provide a simpler route-based API model for Lambda and HTTP integrations with JWT or Lambda authorization options. | Martini APIs, Lambda, HTTP backends, and external applications | Martini calls HTTP API routes or receives routed requests through its REST API, using environment-specific base URLs and credentials. |
| WebSocket APIs | Manage persistent bidirectional communication through routes and connection events. | Real-time applications, AWS backends, and application services | Martini can process related application-level requests where supported, but WebSocket-specific handling depends on the surrounding backend design. |
| Resources and routes | Define URL paths and route keys that determine how API requests are dispatched. | Martini workflows, Lambda, HTTP endpoints, and AWS services | Martini uses route contracts to select workflow behavior, validate payloads, and map path, query, and body values. |
| Methods | Represent REST operations such as GET, POST, PUT, PATCH, and DELETE. | Martini APIs, downstream REST services, and enterprise applications | Martini maps methods to workflow operations, applies validation and business rules, and returns controlled response statuses. |
| Integrations | Connect API Gateway routes or methods to Lambda, HTTP endpoints, AWS services, or mock responses. | Martini APIs, Lambda, Amazon SQS, AWS Step Functions, and HTTP services | Martini can be the integration target or a consumer of the resulting endpoint, while its workflows manage transformation and orchestration. |
Authentication and security considerations
Authentication and authorization
Amazon API Gateway supports IAM authorization, API keys and usage plans, Lambda authorizers, Cognito user pool authorizers, JWT authorizers for HTTP APIs, resource policies, HTTPS endpoints, and mutual TLS options for configured custom domains.
Martini should use the authorization method configured for the specific API and stage. API keys, bearer tokens, JWTs, certificates, and client secrets belong in Martini secrets or environment-specific configuration rather than workflow mappings. IAM SigV4 requests require appropriate signing support or custom implementation.
- Use API keys for consumer identification and usage controls, not as a complete authentication mechanism.
- Validate issuer, audience, scopes, and signing requirements for JWT or Cognito authorization.
- Confirm private API networking, DNS, TLS, firewall, and allowlist requirements for restricted endpoints.
Operational considerations for Amazon API Gateway integrations
Design and operations
- Keep stage URLs, credentials, and environment-specific configuration outside workflow logic.
- Account for API Gateway throttling, usage-plan quotas, payload limits, timeouts, and downstream service limits.
- Implement pagination in the backend contract and preserve continuation tokens in Martini workflows where applicable.
- Use idempotency keys or stable identifiers for retried create and command operations.
- Verify binary media types, base64 behavior, content headers, and proxy event structures for file payloads.
- Test changes to routes, methods, models, authorizers, deployments, and integration responses against Martini mappings.
- Combine API Gateway access and execution logs, CloudWatch metrics, backend logs, and Martini workflow logs using correlation IDs.
- Use bounded retries for transient throttling and server failures, and avoid retrying permanent authorization or validation errors.
Why use Martini instead of scripts or point-to-point integrations?
Integration orchestration
API Gateway manages API entry points, routing, authorization, throttling, stages, and AWS-facing integrations. Martini complements those capabilities by orchestrating multi-step enterprise processes across API Gateway, applications, databases, files, and other services.
- Build reusable workflows instead of duplicating request, mapping, and error logic in point-to-point scripts.
- Expose a controlled Martini API behind API Gateway while keeping transformation and downstream orchestration in Martini.
- Map and transform JSON, XML, binary references, and application-specific payloads using explicit integration models.
- Centralize validation, business rules, idempotency, retries, and operational logging.
- Keep authentication values and environment-specific endpoints configurable across development, test, and production.
Frequently asked questions
Amazon API Gateway integrates through REST APIs, HTTP APIs, WebSocket APIs, HTTPS callback endpoints, and integrations with Lambda, HTTP services, AWS services, or other backends. Enterprise systems can call API Gateway endpoints, send callbacks to them, or consume APIs exposed through API Gateway. Martini can consume these endpoints, expose an API behind API Gateway, and orchestrate mapping, validation, and downstream processing.
Yes. Martini can consume Amazon API Gateway REST and HTTP endpoints, receive callback requests routed through API Gateway, and expose a Martini REST API behind an API Gateway HTTP integration. The authentication method depends on the configured API Gateway authorizer, such as an API key, JWT, Cognito token, Lambda authorizer, or IAM.
No. A dedicated Amazon API Gateway connector is not required. Martini can integrate using API Gateway's native REST and HTTP endpoints, callback routes, authentication mechanisms, and configured backend interfaces.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Amazon API Gateway. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from AWS, API Gateway, backend AWS services, network infrastructure, or other third-party systems based on usage and deployment configuration.
REST APIs are the primary choice where API management features, resources, methods, stages, usage plans, or request transformations are needed. HTTP APIs are suitable for a simpler route model with Lambda or HTTP integrations. Callback endpoints are useful for inbound notifications, while binary payloads and asynchronous routing should be used with awareness of payload, timeout, and backend limitations.
API Gateway can expose HTTPS endpoints that receive webhook-style callbacks from external applications and route them to a configured backend or Martini. It is not an outbound webhook subscription platform and does not provide a universal third-party event feed; the external application must send the callback.
API Gateway routes requests but does not provide a general enterprise synchronization model. Martini workflows can call or receive API Gateway requests, preserve pagination or job identifiers, map JSON or XML payloads to canonical models, apply validation and business rules, and write results to downstream applications. Scheduled workflows can poll status or synchronize data when callbacks are unavailable.
Separate API Gateway-generated authorization, throttling, route, and timeout errors from backend and business errors. Martini can retry bounded transient failures such as selected 429 and 5xx responses, while avoiding retries for permanent validation or authorization failures. Idempotency keys or stable business identifiers should be used to prevent duplicate writes, and API Gateway and Martini logs should share correlation identifiers.
Related Martini documentation
API integration
Callbacks
Workflows
Operations
Connect Amazon API Gateway with Martini
Use Martini to consume Amazon API Gateway endpoints, receive routed callbacks, or expose enterprise workflows behind API Gateway with governed authentication, transformation, and operational handling.