AWS apigateway documentation change
Summary
Removed detailed diagrams, example execution logs, and simplified explanations about REST API development features. Consolidated content about proxy/non-proxy integrations and documentation features.
Security assessment
Changes appear to be editorial improvements removing redundant examples and simplifying explanations. No mention of security vulnerabilities, patches, or new security features. References to IAM permissions and authorizers remain but were not added by this change.
Diff
diff --git a/apigateway/latest/developerguide/rest-api-develop.md b/Users/docs/2025-03-10_15-36-52/apigateway/latest/developerguide/rest-api-develop.md index 28d7b5a81..a5610dcd5 100644 --- a/apigateway/latest/developerguide/rest-api-develop.md +++ b/apigateway/latest/developerguide/rest-api-develop.md @@ -5,2 +4,0 @@ -Example resource for a REST APIAdditional REST API features for development - @@ -11,23 +9 @@ In Amazon API Gateway, you build a REST API as a collection of programmable enti -Each `Resource` entity can have one or more [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) resources. A `Method` is an incoming request submitted by the client and can contain the following request parameters: a path parameter, a header, or a query string parameter. In addition, depending on the HTTP method, the request can contain a body. Your method defines how the client to accesses the exposed `Resource`. To integrate the `Method` with a backend endpoint, also known as the integration endpoint, you create an [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) resource. This forwards the incoming request to a specified integration endpoint URI. If necessary, you can transform request parameters or the request body to meet the backend requirements, or you can create a proxy integration, where API Gateway sends the entire request in a standardized format to the integration endpoint URI and then directly sends the response to the client. - -For responses, you can create a [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) resource to represent a response received by the client and you create an [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) resource to represent the response that is returned by the backend. Use an integration response to transform the backend response data before returning the data to the client or to pass the backend response as-is to the client. - -## Example resource for a REST API - -The following diagram shows how API Gateway implements this request/response model for an HTTP proxy and an HTTP non-proxy integration for the `GET /pets` resource. The client sends the `x-version:beta` header to API Gateway and API Gateway sends the `204` status code to the client. - -In the non-proxy integration, API Gateway performs data transformations to meet the backend requirements, by modifying the integration request and integration response. In a non-proxy integration, you can access the body in the method request but you transform it in the integration request. When the integration endpoint returns a response with a body, you access and transform it in the integration response. You can't modify the body in the method response. - -In the proxy integration, the integration endpoint modifies the request and response. API Gateway doesn't modify the integration request or integration response, and sends the incoming request to the backend as-is. - -Regardless of the integration type, the client sent a request to API Gateway and API Gateway responded synchronously. - -Non-proxy integration - - - - -Proxy integration - - - +Each `Resource` entity can have one or more [Method](https://docs.aws.amazon.com/apigateway/latest/api/API_Method.html) resources. A `Method` is an incoming request submitted by the client and is expressed in the request parameters and body. It defines the application programming interface for the client to access the exposed `Resource`. To integrate the `Method` with a backend endpoint, also known as the integration endpoint, you create an [Integration](https://docs.aws.amazon.com/apigateway/latest/api/API_Integration.html) resource. This forwards the incoming request to a specified integration endpoint URI. If necessary, you can transform request parameters or request body to meet the backend requirements. @@ -35 +11 @@ Proxy integration -The following example execution logs show what API Gateway would log in the previous example. For clarity, some values and initial logs have been removed: +For responses, you can create a [MethodResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_MethodResponse.html) resource to represent a request response received by the client and you create an [IntegrationResponse](https://docs.aws.amazon.com/apigateway/latest/api/API_IntegrationResponse.html) resource to represent the request response that is returned by the backend. You can configure the integration response to transform the backend response data before returning the data to the client or to pass the backend response as-is to the client. @@ -37,49 +13 @@ The following example execution logs show what API Gateway would log in the prev -Non-proxy integration - - - - Wed Feb 12 23:56:44 UTC 2025 : Starting execution for request: abcd-1234-5678 - Wed Feb 12 23:56:44 UTC 2025 : HTTP Method: GET, Resource Path: /pets - Wed Feb 12 23:56:44 UTC 2025 : Method request path: {} - Wed Feb 12 23:56:44 UTC 2025 : Method request query string: {} - Wed Feb 12 23:56:44 UTC 2025 : Method request headers: {x-version=beta} - Wed Feb 12 23:56:44 UTC 2025 : Method request body before transformations: - Wed Feb 12 23:56:44 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets - Wed Feb 12 23:56:44 UTC 2025 : Endpoint request headers: {app-version=beta} - Wed Feb 12 23:56:44 UTC 2025 : Endpoint request body after transformations: - Wed Feb 12 23:56:44 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets - Wed Feb 12 23:56:45 UTC 2025 : Received response. Status: 200, Integration latency: 123 ms - Wed Feb 12 23:56:45 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:56:45 GMT} - Wed Feb 12 23:56:45 UTC 2025 : Endpoint response body before transformations: - Wed Feb 12 23:56:45 UTC 2025 : Method response body after transformations: (null) - Wed Feb 12 23:56:45 UTC 2025 : Method response headers: {X-Amzn-Trace-Id=Root=1-abcd-12345} - Wed Feb 12 23:56:45 UTC 2025 : Successfully completed execution - Wed Feb 12 23:56:45 UTC 2025 : Method completed with status: 204 - -Proxy integration - - - - Wed Feb 12 23:59:42 UTC 2025 : Starting execution for request: abcd-1234-5678 - Wed Feb 12 23:59:42 UTC 2025 : HTTP Method: GET, Resource Path: /pets - Wed Feb 12 23:59:42 UTC 2025 : Method request path: {} - Wed Feb 12 23:59:42 UTC 2025 : Method request query string: {} - Wed Feb 12 23:59:42 UTC 2025 : Method request headers: {x-version=beta} - Wed Feb 12 23:59:42 UTC 2025 : Method request body before transformations: - Wed Feb 12 23:59:42 UTC 2025 : Endpoint request URI: http://petstore-demo-endpoint.execute-api.com/petstore/pets - Wed Feb 12 23:59:42 UTC 2025 : Endpoint request headers: { x-version=beta} - Wed Feb 12 23:59:42 UTC 2025 : Endpoint request body after transformations: - Wed Feb 12 23:59:42 UTC 2025 : Sending request to http://petstore-demo-endpoint.execute-api.com/petstore/pets - Wed Feb 12 23:59:43 UTC 2025 : Received response. Status: 204, Integration latency: 123 ms - Wed Feb 12 23:59:43 UTC 2025 : Endpoint response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} - Wed Feb 12 23:59:43 UTC 2025 : Endpoint response body before transformations: - Wed Feb 12 23:59:43 UTC 2025 : Method response body after transformations: - Wed Feb 12 23:59:43 UTC 2025 : Method response headers: {Date=Wed, 12 Feb 2025 23:59:43 GMT} - Wed Feb 12 23:59:43 UTC 2025 : Successfully completed execution - Wed Feb 12 23:59:43 UTC 2025 : Method completed with status: 204 - -To import a similar API and test it in the AWS Management Console, see the [example API](./api-gateway-create-api-from-example.html). - -## Additional REST API features for development - -API Gateway supports additional features for the development of your REST API. For example, to help your customers understand your API, you can provide documentation for the API. To enable this, add a [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) resource for a supported API entity. +To help your customers understand your API, you can also provide documentation for the API, as part of the API creation or after the API is created. To enable this, add a [DocumentationPart](https://docs.aws.amazon.com/apigateway/latest/api/API_DocumentationPart.html) resource for a supported API entity. @@ -89,4 +16,0 @@ To control how clients call an API, use [IAM permissions](./permissions.html), a -The following diagram shows the features available for REST API development and where in the request/response model these features are configured. - - -