AWSAWS Certified Generative AI Developer - Professional2026-102.4 Implement FM API integrations
Validate both sides of model inference
Completed by the knowledge check
Learning objective
Validate incoming API requests with API Gateway request validators and validate FM response schemas in application code.
Core idea
A foundation model (FM) integration crosses two independent data boundaries. The request boundary decides whether input may reach inference. The response boundary decides whether generated content may become an application result. A schema at one boundary does not validate the other.
API Gateway can reject structurally invalid requests before invoking a REST API integration. Application code must still enforce caller permissions, model-specific constraints, and the meaning of the input. After inference, that code must distinguish a valid service response from a valid domain result.
Use separate contracts for the public API, the model request, and the generated result. Sharing field names is convenient, but sharing one schema across all three can hide different trust assumptions and incompatible validation capabilities.
How it works
Configure validation on the REST API method
API Gateway request validators are a REST API feature. The AWS comparison of REST APIs and HTTP APIs lists request validation for REST APIs and not for HTTP APIs. If you choose an HTTP API, implement the equivalent checks in the backend rather than assuming the REST validator configuration applies.
A RequestValidator has validateRequestBody and validateRequestParameters flags. Assign the validator to each method that requires it; creating a validator without attaching it to the method does not establish the boundary. Associate a request model with the appropriate content type when validating the body.
For required URI, query-string, and header parameters, API Gateway checks that they exist and are not blank. It does not validate their type or format. A nonblank document_id is therefore not proof of a well-formed identifier or permission to read that document. Validate those properties in application code using the trusted caller identity.
For request bodies, API Gateway models use JSON Schema draft 4. Define required fields and expected types in the method’s request model. A validation failure produces a 400 response before the integration request and publishes validation results in CloudWatch Logs. This prevents an invalid public request from consuming model work merely because its JSON parses.
Content-type matching matters. If API Gateway finds no matching model for the request content type, body validation is not performed. Use a $default model when the same schema must apply regardless of content type, and implement an explicit policy for accepted content types. Request validation and passthrough behavior for unmatched mapping templates are separate settings; configuring one does not silently configure the other.
Validate the inference input in the application
After the edge checks pass, validate the normalized application request. Confirm that the selected document belongs to the caller, that required business context exists, and that requested output behavior is permitted. Derive identity-sensitive values from trusted authentication context rather than accepting them from the body.
The model adapter then constructs its own supported request. A public schema containing question and document_id does not establish that a resulting Converse content block or native InvokeModel body is valid. The adapter must enforce the selected model’s interface and input budget. See 1.3.6–1.3.7 for model payload contracts and 1.3.9 for context budgets.
Keep public validation errors distinct from adapter defects. For example, reject an absent question at the API boundary, while a misconfigured model parameter should identify an integration failure. Returning every failure as an invalid user request hides a broken deployment and makes safe recovery harder.
Decode and validate the generated result
For Converse, inspect stopReason and extract the relevant content from output.message. Do not assume the response envelope is your domain JSON. If the application expects a final answer, tool_use means another stage is required, while max_tokens can mean the intended result is incomplete. A guardrail_intervened result belongs in the application’s safety outcome, not an automatic schema-repair loop.
For a structured result, first parse the generated content as JSON. Then run the application’s validator against its versioned result schema. Required fields, allowed values, unknown-field policy, and nested types are application choices. A JSON parser proves syntax; it does not prove those properties.
Next apply semantic checks that a structural schema cannot settle: whether a cited document was actually supplied, whether a proposed action is authorized, or whether a monetary amount is within the workflow’s permitted range. Preserve a clear outcome such as accepted, invalid_result, or incomplete_result in the application contract. These labels are application states, not Bedrock response fields.
Only a result that passes every check on the response path is accepted.
API Gateway uses draft 4 models, while Bedrock structured outputs through Converse outputConfig.textFormat or strict tool definitions (strict: true) use a Draft 2020-12 subset without numeric or string-length constraints; see 1.6.1.
Check model and inference-profile support before enabling that capability; it is not universal. Even when structured outputs enforces the supported shape, the application still owns range checks, provenance, authorization, and the public result contract.
Key distinctions and trade-offs
Presence versus validity: API Gateway parameter validation establishes nonblank presence. Application checks establish type, format, authorization, and business meaning.
Syntax versus schema versus semantics: Parseable JSON can violate the result schema. Schema-compliant JSON can still contain an unsupported claim or forbidden action. Each check establishes a different property.
Constrained generation versus accepted results: Structured outputs reduces malformed generation where supported. It does not make model-selected values authoritative or eliminate the application’s acceptance decision.
Early rejection saves backend work and improves failure clarity, but the edge model is deliberately incomplete. Backend validation costs application code and maintenance; it protects the boundaries that transport validation cannot express. Version the contracts together while retaining their separate responsibilities.
Architecture / decision scenario
An expense assistant proposes a categorized reimbursement record. Its REST method attaches a request validator with both flags enabled and a body model for the accepted payload. Missing fields fail before Lambda runs. A nonblank employee header still reaches the backend, which binds employee identity to authenticated context and checks access to the receipt.
The model returns a structured proposal through Converse. Where the chosen model supports it, outputConfig.textFormat constrains the category and field types. The application checks stopReason, parses the content, validates the result schema, and separately enforces an allowed amount and receipt provenance. The numerical range remains an application check because the Bedrock schema subset does not support maximum.
A truncated proposal becomes incomplete_result; a prohibited amount becomes invalid_result. Neither triggers a reimbursement. If the service moves to an HTTP API, the team retains these checks and moves request-shape validation into the backend, because that API type does not supply REST request validators.
Common exam traps
- Assuming REST request validators also apply to HTTP APIs.
- Treating a nonblank query parameter as type- or format-validated.
- Ignoring unmatched content types that skip body validation.
- Equating successful JSON parsing with response-schema validation.
- Copying one schema between draft 4 and Bedrock’s supported subset unchanged.
- Using a valid generated shape as proof of authorization or factual correctness.
What to remember
Attach and scope the API Gateway validator, then validate what only the application knows. On the response path, inspect completion, parse content, validate structure, and enforce semantics before publishing a result. Structured generation strengthens one boundary without replacing the others.
Knowledge check
An expense assistant’s API moves from an API Gateway REST API, where a request validator checked the body against a model, to an HTTP API to cut cost. Requests must still be rejected when required fields are missing. What does the migration need?
RequestValidator to the HTTP API’s routesA REST API method requires the query parameter document_id, and its request validator has validateRequestParameters enabled. A request arrives with document_id=../../payroll. What has API Gateway established about this parameter?
A REST method validates request bodies against a model defined for application/json. Clients that send the same JSON as text/plain reach the Lambda integration with missing fields. Which change applies the schema to them as well?
validateRequestParameters on the method’s validatorWHEN_NO_MATCH$default content typetext/plain to the method$default model applies one schema regardless of content type, alongside an explicit policy on accepted types. Passthrough behavior for unmatched mapping templates is a separate setting, and parameter validation does not inspect the body.A reimbursement proposal comes back through Converse structured outputs, and no proposal may exceed 500 in amount. An engineer adds "maximum": 500 to the amount field of the outputConfig.textFormat schema. What will happen, and where does the cap belong?
maximum , and a schema with unsupported features is rejected with a 400 error. The range is an application check on the parsed result, alongside provenance and authorization; a request model validates incoming requests, not generated output.