How to describe AWS GatewayAPI in file and import? - amazon-web-services

We are using Amazon Gateway API and currently we describe API endpoints manually through the web console.
Is it possible to create definition of API in some file(s) and import it?
Why do we need this:
We want every change in the API be reviewed (it's our development process) by other people.
In case if API is deleted or broken accidently, we want to be able to restore it easily.
By now the only solution I see is to write script, based on aws apigateway command line command that creates all resources and methods.
But probably there is a better way to do it?
Thanks!
P.S. It may partially overlaps with this question: exporting api definition from AWS api gateway.

I think the Swagger Importer feature of AWS API Gateway is what you are looking for: https://aws.amazon.com/about-aws/whats-new/2015/07/introducing-swagger-importer-easily-import-swagger-api-definitions-into-amazon-api-gateway/

You can export your API definition with API Gateway extensions into swagger format. Then you use the API Gateway API importer to import/update your API.

If you are backing your API Gateway endpoints with Lambda functions you may want to check out the serverless project https://github.com/serverless/serverless
Using this framework you have a JSON file that describes your endpoints and binds them to your Lambda code in the same project structure. The tool lets you deploy the endpoints or code from the command line. It also allows you to manage other AWS resources in a CloudFormation template in the same project structure and deploy it from the command line.

Related

Using openapi definitions aws api gateway

I'm new to api gateway stuff and have created an api gateway using terraform on aws. Now I want to expose more apis on the same api gateway. I have used the body argument on Terraform which takes a definition file. If I use a new open api definition, my existing ones are replaced by Terraform. What is the best way in this situation. Appending new apis to openapi file or?
please advise.

How to use CloudFromation to update a single API Gateway consists of multiple services

I have a single api gateway consists of several services's endpoints (let's say service A, B, C, D). When a single service A update, I would like to dynamically update the api gateway for service A only and keep service B, C, D unchanged. And I have a maven plugin to generate swagger file for each service.
To make this work, I have to solutions:
Use AWS CLI to do api gateway update in merge mode by swagger file of service A and do redeployment.
Merge all swagger files of service A, B, C, D to a single swagger file and upload this single swagger file to S3 bucket. Then I can use CloudFormation template to create api gateway (with S3BodyLocation to my swagger file in previous step) and redeploy.
My question is, is there an easier way that I can use CloudFormation to update api gateway for single service like aws cli without need to merge all services' swagger files? Or any other solution that can achieve my goal? If not, which of my solution is better? Thank you.
PS. I am also curious about how people using single api gateway for microservices, for me it looks like there is no way to avoid merging multi swagger files from all services before using it to create api gateway.
With AWS::Serverless::Api, you should use DefinitionBody property.
Here comes excellent example Realworld-serverless.
You could look at SAM which will help you to generate your API Gateway a little simpler than traditional CloudFormation but will still generate the CloudFormation stack for you.
Take a look here: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-api.html

How to properly expose APIs from Fargate tasks?

I deployed few microservices into Fargate. Each microservice will have around 30 API endpoints.
I have AWS ALB which will do the path based routing to the Fargate.
I created API Gateway APIs to externally expose the APIs. API Gateway integration method is HTTP and that points to the ALB endpoint.
Is this the proper way to setup the microservices? If not, please suggest the better approach.
And also, I want to automatically import the Swagger definition into API Gateway whenever there is a change in the Swagger definition. Swagger definition is exposed under /apidocs of each microservice. How do I automate the import of swagger definition into API gateway? Is there a commonly used approach?
Keep in mind you'll need to update both API GW and ALB paths. To import new swagger definition you'll need some kind of triggered event to:
Upload new swagger definition to S3.
Create an API gateway deployment.
Perform the path edition in ALB target group(s). This one could be done by triggering a CLI or API call (or sdk).
If you use CloudFormation, you could trigger an UPDATE containing all these new changes too. If so, also keep an eye on those resources parameters that may or not require a resource replacing.
Hope it helps.

How to access AWS API Gateway documentation using Swagger UI

I have created API using AWS Api Gateway. Then i have documented documentation parts for all the entities ( like API, RESOURCE, METHOD, MODEL etc). Then using AWS Gateway Console i have published the documentation to dev stage with version 1
But i am not sure how do i (or the consumer of the API) going to access the documentation?
There is an Export option that can export documentation as Swagger or OpenAPI3. This will create .json or .yaml file and then consumer has to import these files into swagger UI. However this is not user-friendly option to provide swagger file every time i update documentation to all consumers.
I was wondering, after publishing the documentation is there anyway consumer can access documentation directly via http. So lets assume my dev stage api URL is
https://devapi.example.com/v1 so something like https://devapi.example.com/v1/help should launch Swagger UI with latest published swagger file.
Update 1
In ASP.NET Web API or .NET Core you can include Swashbuckle that creates swagger files and also has embedded version of the Swagger UI tool. So after deploying API user can access documentation directly from UI something like https://devapi.example.com/swagger.
I was hoping the same thing from AWS gateway. After publishing the documentation it should make that documentation available via some predefined resource path.
AWS API Gateway can only make documentation exportable but won't render a UI app. There is no endpoint that you can use in the gateway to render the documentation. You may wish to use third party tools or AWS API Gateway Developer Portal to allow users browse API documentation. You may find this blog helpful.
Micro Swagger imports swagger spec from Amazon API Gateway & serves a swagger UI from it.
You can leave it running on an EC2 instance:
npm i -g micro-swagger
micro-swagger start
It'll use the instance's IAM role to download the Swagger spec from API Gateway. Your CI/CD pipeline can restart/refresh Micro Swagger whenever it deploys. Your customers can see the latest API docs at the instance's domain.

AWS API Gateway: How to achieve continuous delivery?

I'm building an API using AWS API Gateway and AWS Lambda. I would like to achieve continuous delivery for this API. The path I've chosen to do it is to use CloudFormation through AWS CodePipeline. I've managed to to it for another project using Lambdas (without API Gateway), it works perfectly and it is really pleasant to use.
The issue I'm facing when deploying is that the Lambdas are properly updated but not the API definition. From what I understand, the AWS::ApiGateway::Deployment are immutable resources which means that for each deployment of the API I need to create a new AWS::ApiGateway::Deployment resource. This is not practical at all because for each of this AWS::ApiGateway::Deployment I have a new Invoke URL. This is not acceptable since I would have to either change my DNS record to the newly deployed API invoke URL or ask our API users to change the URL in their applications.
What I would like is to be able to change the API definition and the Lambdas implementations without my API users having to change anything in their applications.
How can I achieve this behavior?
I created a tutorial to highlight my issue. You can find it at: https://github.com/JonathanGailliez/aws-api-gateway-lambda-example
As per: https://forums.aws.amazon.com/thread.jspa?messageID=789869&#789869
joey-aws says:
We are currently in the process of rolling out a solution which
addresses this exact problem. In the meantime, a common workaround
would be to update something small, such as a "description" field
which could then be used to "trigger" an API Gateway deployment when
updating the CloudFormation stack.
I'll update this answer and the example repo once it's rolled out.
You could run a Cloudformation update from the command line or in the AWS console. This would change the API definitions and any lambda code without changing the unique id to access your gateway.
The other option is to put your API behind a custom domain name and then you could keep deploy a new API or stage and switch over the custom domain mapping when you are ready. The users wouldn't recognize any change.
A way to achieve that is by leveraging existing frameworks like
AWS SAM
Serverless
Claudia
I was able to achieve this by using CloudFormation template generated by troposphere and boto3 api in Python as follows:
Split the template into two parts
API definition, Method(s), IAM roles, ApiKey and Lambda (a)
Deployment, UsagePlan and UsagePlanKey (b)
Once changed Lambda code is zipped up and uploaded to S3 using boto3 api
Stack (b) is deleted
Stack (a) is updated with new resource id for the GET method connected to lambda
Stack (b) is created anew
Steps 3, 4, 5 are performed using CloudFormation boto3 api with blocking until completed.
Most importantly after all steps are done ApiKey value and stage Invoke URL remain the same, running updated Lambda code as tested with curl.
Note: it may take additional 30-60s for API to become fully functional after CloudFormation update is completed.