AWS: Expose ECS Service via API Gateway- Part 2
This is the second part of the series. Make sure you have read the first. Here we will see how to deploy API-Gateway and best use Open API Spec.
API-Gateway
Importing Open API
- Get the Swagger Document (V2 or V3) for the service to be exposed.
- Create API → REST API (Import) → Paste the swagger document → Import
Swagger Document Troubleshooting.
- 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 swagger editor.
VPC Link
- Create a VPC Link for the NLB created earlier. Note Down the VPC Link ID created.
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
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
6. Now you will be able to access the API endpoint from outside the VPC.
Cognito Authorizer
- Add Cognito Authorizer as shown below
Token Source: Authorization
2. Add Authorizer to each endpoint
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 via Postman 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.
- Select individual HTTP method → Actions → Enable CORS → Enable CORS and replace existing CORS headers.
- 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
- Create an HTTP Status code 200 in OPTIONS. (Method Response)
2. Declare the missing CORS header
Access-Control-Allow-Headers
Access-Control-Allow-Methods
Access-Control-Allow-Origin
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: ‘*’
Manually Adding missing CORS header in GET [and other HTTP Status]
- Declare missing CORS header in Method Response
2. Set the values for CORS headers in the Integration Response.
3. You can also provide regex to generalize the Integration Response.
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.
Bonus!
Make the best use of Open API Spec 3
Will see how to best use Open API Spec in the API-First approach.
- Developer Docs: reDoc
- Execute API’s from Swagger Editor
- Open API IDE: Stoplight
- 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 AWS Developer portal.
Else you can provide the server configuration in OAS3 and others can use it directly from the Swagger editor (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
Stoplight Studio 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 Github release page.
You should go with API-First approach if API is your product.
For frontend devs, they can set a mock server with Stoplight & Prism 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 swagger editor, 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 👏.
