We created an API from scratch with CORS enabled. We did it using both AWS CLI commands and the CloudFormation template. Let's first understand the CLI steps in detail.
The first four steps with the CLI are similar to what we have seen in recipes in Chapter 2, Building Serverless REST APIs with API Gateway:
- Create an API
- Get the ID of the root resource
- Create a resource greeting
- Create a subresource with a path parameter
The next four steps create the GET method:
- put-method for the GET method
- put-method-response for the GET method
- put-integration for the GET method
- put-integration-response for the GET method
The put-method subcommand and put-integration subcommand are similar to what we have seen in the recipes of Chapter 2, Building Serverless REST APIs with API Gateway. The put-method-response and put-integration-response subcommands now also should specify the response-parameters property.
The response-parameters property of the put-method-response subcommand contains a key-value map specifying required or optional response parameters that the API can send back in the response. The key of this map is a method response header name and the value is a Boolean flag indicating whether the method response parameter is required or not (true for required and false for optional).
The response-parameters property of the put-method-integration subcommand contains a key-value map that specifies the response parameters that are passed to the method response from the backend (mock integration in our case). The key is a method response header parameter name and the value is an integration response header value, a static string value enclosed within single quotes, or a JSON expression from the integration response body.
As we can see from the previous section, we need to use four subcommands to configure an HTTP method with API Gateway when using the AWS CLI. However, with a CloudFormation template, we needed only one resource of type AWS::ApiGateway::Method:
The next four steps create an OPTIONS HTTP method for the resource:
- put-method for the OPTIONS method
- put-method-response for the OPTIONS method
- put-integration for the OPTIONS method
- put-integration-response for the OPTIONS method
OPTIONS is required for the preflight requests.
For Ajax and HTTP request methods, especially for ones that can modify data, such as non-GET methods, or for POST method with certain MIME types, the specification mandates browsers to preflight a request to server, asking for supported methods with an HTTP OPTIONS request. The server responds back with a header Access-Control-Allow-Methods that lists all support methods other than GET (for example, DELETE). The browser will then send the actual request only for the supported HTTP request methods.
The OPTIONS response should also contain the headers Access-Control-Allow-Origin and Access-Control-Allow-Headers. The Access-Control-Allow-Origin header specifies the servers (origins) that can access a particular resource. A value of * in our case indicates that any other domain name can access it with CORS. In practice, you may make it more specific to particular domains. The Access-Control-Allow-Headers header specifies the headers that are allowed in the actual request. We just specified the basis headers Content-Type, Authorization, X-Amz-Date, X-Api-Key, and X-Amz-Security-Token.
Even if we only use a GET URI, we still need the OPTIONS method configured as we are making an AJAX call with the XMLHttpRequest object. With the XMLHttpRequest object, we can exchange data with a web server without reloading the whole page. All modern web browsers have a built-in support for the XMLHttpRequest object. In our case, the Access-Control-Allow-Methods header may be empty or not specified with the put-method-integration subcommand, since we are not supporting any other methods than GET (it still has to be defined with the put-method-response subcommand, but we can specify it as optional).
Finally, we deploy the API and then test it using CodePen:
- Deploy the API
- Execute the URL from CodePen