Expose ECS Service via API Gateway- Part 2

API Gateway with Cognito

This is the second part of the series. Make sure you have read the . Here we will see how to deploy API-Gateway and best use Open API Spec.

API-Gateway

Importing Open API

  1. Get the Swagger Document (V2 or V3) for the service to be exposed.
  2. Create API → REST API (Import) → Paste the swagger document → Import

Swagger Document Troubleshooting.

  1. If you find any issues like

Request header “Content-Type” is not being sent with request #1361

Try adding

2. Try verifying the Swagger Document by pasting it in the .

VPC Link

  1. Create a VPC Link for the NLB created earlier. Note Down the VPC Link ID created.
VPC Link
VPC Link ID

2. Go to the Imported API Gateway, and select any HTTP Method. Select VPC Link from the options. And fill in the below details.

VPC Link : [Use Stage Variables]

VPC Link ID: ${stageVariables.vpcLinkId}

Endpoint URL : http://${stageVariables.endpointdomain}/api/v1/complete-endpoint

Configure VPC Link

3. End result would look like the below one

4. Now deploy the API.
Actions → Deploy API → [New Stage] → Name it as dev → Deploy

5. Now go to the stage variable section in the deployed API. Fill in these variables.

endpointdomain: NLB-**.elb.ap-northeast-1.amazonaws.com:8081

vpcLinkId: VPC_ID

Stage Variables

6. Now you will be able to access the API endpoint from outside the VPC.

Cognito Authorizer

  1. Add Cognito Authorizer as shown below

Token Source: Authorization

Cognito Authorizer

2. Add Authorizer to each endpoint

Auth scope.

NOTE: You can define custom auth scope for Authorization to this endpoint.

3. Try accessing the endpoint from the browser. It will show Unauthorized.

4. You can try accessing the endpoint with OAuth2 to verify if the Authorization worked or not.

Enable CORS

Now you are able to access it from Postman. But to access it from a web app, you need to enable CORS.

  1. Select individual HTTP method → Actions → Enable CORS → Enable CORS and replace existing CORS headers.
  2. Once you are done, you get an OPTIONS method under the URL path.

How CORS work?

a. Initially, the browser sends a preflight request to the OPTIONS method.

b. If the OPTIONS method allows all the headers being passed and returns 200 status, the request is sent to the actual HTTP Method.

3. We need to verify the OPTIONS headers. If it is not automatically added, we need to add it manually.

Manually Adding missing CORS header in OPTIONS

  1. Create an HTTP Status code 200 in OPTIONS. (Method Response)
Add 200 Status Code

2. Declare the missing CORS header

Access-Control-Allow-Headers
Access-Control-Allow-Methods
Access-Control-Allow-Origin

CORS headers

2. Add missing header values in the CORS (Integration Response)

Access-Control-Allow-Headers: ‘Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token,x-apigw-api-id,Origin,x-amzn-oidc-identity,x-amzn-oidc-data,oidc-identity,oidc-data,config_additionalParam’
Access-Control-Allow-Methods: ‘GET,PUT,POST,DELETE,HEAD’
Access-Control-Allow-Origin: ‘*’

CORS Values

Manually Adding missing CORS header in GET [and other HTTP Status]

  1. Declare missing CORS header in Method Response
Missing CORS headers

2. Set the values for CORS headers in the Integration Response.

CORS header values.

3. You can also provide regex to generalize the Integration Response.

Regex

Status Code Mapping

If we don’t have HTTP status code mappings in the API-Gateway, every response would be of status 200 (the default mapping). This is because

  • API Gateway is a barrier which will stop the client request →
  • sends a new request from API-Gateway to the NLB service →
  • Receives the response →
  • Send back the response as a response from API-Gateway

It is very important to have the status code mapping defined in the API-Gateway to get the correct response status from the underlying service.

In case, you don’t have the status code mapping for say, 400, 500 etc, we need to define that explicitly and add the CORS headers as well.

Default Gateway Response

If there is a CORS issue on 404 response etc(which are send by the gateway and not the service), we may need to add CORS headers in the Default Gateway Response.

404 CORS headers

Bonus!

Make the best use of Open API Spec 3

Will see how to best use Open API Spec in the API-First approach.

  1. Developer Docs: reDoc
  2. Execute API’s from Swagger Editor
  3. Open API IDE: Stoplight
  4. Swagger Editor features.

1. Developer Docs [reDoc]:

Please have a look at API-Documentation of some products

You can simply create this server/HTML page with few commands.

Setup

2. Execute API’s from Swagger Editor

If you have exposed your APIs via API Gateway, you can set up an

Else you can provide the server configuration in OAS3 and others can use it directly from the (If CORS is enabled).

If you have added Authentication, you can add the Auth details in OAS3 doc as well.

3. Open API IDE: Stoplight

is the best IDE for creating and modifying OAS.

In case you have any trouble setting up the IDE with the latest version, try using the older ones from there page.

You should go with API-First approach if API is your product.

For frontend devs, they can set a mock server with & to send dummy response. So if we get the OAS3 created first, developers can parallelly start there work with the mock server. ( Automation Tester, Frontend Dev)

4. Swagger Editor features

In the , you have the below features that you might have missed out

  • Convert to OAS3 ( Edit → Convert to OpenAPI 3)
  • Create a mock server in any platform, including spring ( Generate Server)
  • Create client-side DTOs etc (Generate Client)

Conclusion

We have finally deployed the web-app complaint API via API-Gateway. We have also seen how to make it consumer-ready. In future articles, we may look into automating this process using Open API Spec.

Found it Interesting?
Please show your support by 👏.

Writes on Big Data, AWS & Backend technologies.

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store