{"id":20285476,"url":"https://github.com/mramshaw/api-gateways","last_synced_at":"2025-03-04T04:09:59.369Z","repository":{"id":92905047,"uuid":"193155550","full_name":"mramshaw/API-Gateways","owner":"mramshaw","description":"Exploring API Gateways (starting with AWS)","archived":false,"fork":false,"pushed_at":"2019-08-05T01:08:16.000Z","size":521,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-14T08:12:13.597Z","etag":null,"topics":["api-gateway","cloud-endpoints","faas","json-schema","restful","serverless","swagger"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mramshaw.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-06-21T20:18:38.000Z","updated_at":"2019-08-19T11:40:03.000Z","dependencies_parsed_at":"2023-06-13T02:31:00.243Z","dependency_job_id":null,"html_url":"https://github.com/mramshaw/API-Gateways","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mramshaw%2FAPI-Gateways","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mramshaw%2FAPI-Gateways/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mramshaw%2FAPI-Gateways/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mramshaw%2FAPI-Gateways/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mramshaw","download_url":"https://codeload.github.com/mramshaw/API-Gateways/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241780512,"owners_count":20019061,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-gateway","cloud-endpoints","faas","json-schema","restful","serverless","swagger"],"created_at":"2024-11-14T14:26:57.852Z","updated_at":"2025-03-04T04:09:59.349Z","avatar_url":"https://github.com/mramshaw.png","language":null,"readme":"# API Gateways\n\n![API Gateway](images/ApplicationServices_AmazonAPIGateway.svg) ![Cloud Endpoint](images/Cloud_Endpoints.svg)\n\nGetting started with API Gateways (AWS versus GCP, starting with AWS first)\n\n## Contents\n\nThe contents are as follows.\n\n* [Motivation](#motivation)\n* [AWS](#aws)\n    * [Protocol](#protocol)\n    * [Endpoint Type](#endpoint-type)\n    * [Workflow](#workflow)\n    * [Caching](#caching)\n    * [GraphQL](#graphql)\n* [GCP](#gcp)\n    * [Limiting API Requests](#limiting-api-requests)\n    * [Cloud Endpoints Portal](#cloud-endpoints-portal)\n* [Swagger](#swagger)\n    * [Swagger with AWS](#swagger-with-aws)\n    * [Swagger with GCP](#swagger-with-gcp)\n* [Testing](#testing)\n* [X-Ray](#x-ray)\n* [Synchronous](#synchronous)\n* [Authentication](#authentication)\n* [Networking](#networking)\n* [Pricing](#pricing)\n* [Reference](#reference)\n    * [AWS API Gateway](#aws-api-gateway)\n    * [JSON Schema](#json-schema)\n    * [WebSockets](#websockets)\n    * [Postman](#postman)\n* [To Do](#to-do)\n\n## Motivation\n\nFollowing the [Single responsibility principle](http://en.wikipedia.org/wiki/Single_responsibility_principle)\n(the __S__ in SOLID) and likewise [Separation of concerns (SoC)](http://en.wikipedia.org/wiki/Separation_of_concerns),\ndecoupling application logic from plumbing is probably a serverless ___best practice___.\n\nAPI gateways can be used for:\n\n* Filtering input data based on request and response mapping models\n* Decoupling authorization and authentication from business logic\n* Traffic throttling and rate limiting\n* DDOS protection\n\nFrom:\n\n    http://docs.aws.amazon.com/lambda/latest/dg/with-on-demand-https.html\n\n\u003e Amazon API Gateway also adds a layer between your application users and your app logic that enables the following:\n\u003e\n\u003e * Ability to throttle individual users or requests.\n\u003e\n\u003e * Protect against Distributed Denial of Service attacks.\n\u003e\n\u003e * Provide a caching layer to cache response from your Lambda function.\n\n## AWS\n\nStarting with AWS, the steps are:\n\n1. Sign up for [AWS](http://aws.amazon.com/)\n2. Create an [IAM Administrator](http://docs.aws.amazon.com/IAM/latest/UserGuide/getting-started_create-admin-group.html)\n\n[This is probably overkill for startups and smaller organizations, however the key takeaway of NOT using the __root__ account for everyday work applies.]\n\nOnce you have created a __non-root__ user account you should sign out and sign back in again (and AWS may even force you to do this).\n\n#### Protocol\n\nAPI Gateway supports REST APIs and [WebSocket APIs](#websockets).\n\n#### Endpoint Type\n\nEndpoints can be [edge-optimized, regional, or private](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-api-endpoint-types.html).\n\nThe default is __Regional__, which is fine for development or a proof of concept.\n\nPrivate endpoints require VPCs.\n\n#### Workflow\n\nWhen working with Lambda functions, the workflow for individual calls is along the following lines:\n\n    Method Request --\u003e Integration Request --\u003e Method Response --\u003e Integration Response\n\nAPI Gateway mappings and models can be defined as needed. Defining them can be troublesome.\n\n__Pro Tip:__ Leave the integration response empty for a ___passthrough response___.\nIf no mapping is defined the response from the Lambda function will be passed-through as-is.\nMy advice would be to check that this does what is expected before defining any models or mappings.\nIn fact, for performance reasons (no response-processing in the API Gateway) this is probably the\noptimal situation.\n\nAWS uses a subset of [JSON Schema](http://json-schema.org/), so if you need any specific features,\nbe aware that the API Gateway may not support them (you will not be able to save the mapping if\nthis is the case).\n\nThe API Gateway uses [Apache Velocity](http://velocity.apache.org/) to do the request \u0026 response mappings.\n\nThe Apache Velocity developer guide is available [here](http://velocity.apache.org/engine/devel/developer-guide.html).\n\nThe Apache Velocity templating reference documentation is available [here](http://velocity.apache.org/engine/devel/vtl-reference.html).\n\n#### Caching\n\nAPI Gateway caching is a premium service and operates prettty much as you would expect.\n\n\u003e When you enable caching for a stage, only GET methods have caching enabled by default. This helps to ensure the safety\n\u003e and availability of your API. You can enable caching for other methods by\n\u003e [overriding method settings](http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html#override-api-gateway-stage-cache-for-method-cache).\n\n[Note that API Gateway caching is enabled by the stage.]\n\nAnd:\n\n\u003e The default TTL value for API caching is 300 seconds. The maximum TTL value is 3600 seconds. TTL=0 means caching is disabled.\n\nAnd:\n\n\u003e Caching is charged by the hour and is not eligible for the AWS free tier.\n\nAnd:\n\n\u003e When API caching is enabled, you can flush your API stage's entire cache to ensure your API's clients get the most recent responses from your integration endpoints.\n\nFrom:\n\n    http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html\n\n__TL;DR__ API Gateway caching should not be enabled until it is needed.\n\n#### GraphQL\n\n[GraphQL](http://graphql.org/) describes itself as \"A query language for your API\".\n\nIf your only reason for considering GraphQL is over-fetching, it is simple to create a new endpoint\nfor your API and only return a subset of fields (whether or not this is \"RESTful\" is another issue).\n\nThis endpoint can then be protected, rate-limited or cached by the API Gateway as appropriate.\n\n__TL;DR__ The API Gateway can provide a limited subset of GraphQL capabilities.\n\n[This is easier than using GraphQL as the API Gateway enables caching and rate-limiting, which are\n non-trivial with GraphQL.]\n\n## GCP\n\nThe Google equivalent to AWS API Gateway are their [Cloud Endpoints](http://cloud.google.com/endpoints/).\n\n\u003e Develop, deploy, protect and monitor your APIs with Google Cloud Endpoints. An NGINX-based proxy and distributed architecture give\n\u003e unparalleled performance and scalability. Using an Open API Specification or one of our API frameworks, Cloud Endpoints gives you\n\u003e the tools you need for every phase of API development and provides insight with Stackdriver Monitoring, Trace and Logging. \n\nCloud Endpoints went GA [February 13, 2017](http://cloud.google.com/blog/products/gcp/google-cloud-endpoints-now-ga-a-fast-scalable-api-gateway).\n\n[Well worth a read for some background on what the article describes as a \"a fast, scalable API gateway'.]\n\n#### Limiting API Requests\n\nIt is possible to rate-limit Google Cloud Endpoints:\n\n    http://cloud.google.com/endpoints/docs/openapi/quotas-overview\n\n[Note that this feature is listed as being in ___Beta___ (or a ___pre-release state___).\n In Google-speak this means the feature(s) is/are stable but may change in the future.]\n\n#### Cloud Endpoints Portal\n\nGoogle Endpoints can be examined with their [Cloud Endpoints Portal](#swagger-with-gcp).\n\n## Swagger\n\n[Swagger](http://swagger.io/) is a great tool for defining and publishing APIs.\n\n[There is also [RAML](http://raml.org/) but as both AWS and GCP support a swagger workflow I won't be looking at RAML.]\n\n#### Swagger with AWS\n\nIn AWS it is possible to import a Swagger definition:\n\n![Swagger imported](images/Swagger_imported.png)\n\n[Here I imported the [Swagger definition](swagger.json) from my [Simple REST API](http://github.com/mramshaw/Simple-REST-API) repo.]\n\nSwagger uses the [OpenAPI Specification](http://swagger.io/specification/) while the API Gateway uses [JSON Schema](#json-schema).\n\n![Models are declared using JSON Schema](images/Model_JSON_Schema.png)\n\nThese two specifications overlap to a great deal but are not fully compatible.\n\nThe Swagger website has a useful page which describes the differences between the OpenAPI Specification and JSON Schema:\n\n    http://swagger.io/docs/specification/data-models/keywords/\n\n\u003e OpenAPI 3.0 uses an extended subset of [JSON Schema Specification](http://json-schema.org/) Wright Draft 00 (aka Draft 5)\n\u003e to describe the data formats. “Extended subset” means that some keywords are supported and\n\u003e some are not, some keywords have slightly different usage than in JSON Schema, and additional\n\u003e keywords are introduced.\n\n__TL;DR__ Swagger can be a useful shortcut to get up and running but is probably not suitable for the definitive statement\nof an API for API Gateway purposes.\n\n#### Swagger with GCP\n\nGoogle Endpoints can be examined with their\n[Cloud Endpoints Portal](http://cloud.google.com/endpoints/docs/frameworks/dev-portal-overview)\nwhich seems to be the Google equivalent to exporting a swagger definition from API Gateway and then\nimporting it into `Postman` or `swagger-ui`: ___it allows developers to explore the API___.\n\nThere is a demo version of this [portal](http://endpointsportal.endpoints-portal-demo.cloud.goog/) which you can even try with your own API:\n\n![Try your own API](images/Try_your_own_API.png)\n\n[Google supports [OpenAPI v2](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md),\n also they seem to be very cognizant that a startup may view an API as confidential.]\n\nHere I import the [Swagger definition](swagger.json) from my [Simple REST API](http://github.com/mramshaw/Simple-REST-API) repo:\n\n![Swagger imported into Portal](images/Swagger_imported_into_Portal.png)\n\n## Testing\n\nOn AWS, once an API has been deployed it can be used as a trigger for FaaS (Lambda functions on AWS).\n\nSDKs can be generated for Android, javascript, iOS (Objective-C, Swift), Java and Ruby.\n\nVarious flavours of `swagger` can be exported, making it simple to test with [Postman](#postman) or `swagger-ui`.\n\nFor Google, it is probably simplest to test with their Cloud Endpoints Portal.\n\nFor RESTful APIs it is also straightforward to test with `curl` or `httpie`.\n\nHowever, for AWS their API Gateway also provides good testing tools (and these are probably the place to start).\n\nIt's really a personal preference which testing tools to use.\n\n## X-Ray\n\n![AWS X-Ray](images/DeveloperTools_AWSX-Ray.png)\n\nIn order to gain some visibility into API Gateway networking, it is simple to activate\n[AWS X-Ray](http://docs.aws.amazon.com/xray/latest/devguide/aws-xray.html).\n\n[Sampling rules can be set for X-Ray to avoid the costs associated with sampling every invocation.]\n\n## Synchronous\n\nLambda functions are great for glue code in many circumstances. They have multiple uses.\n\nIt may not be clear from __node.js__ examples, so it's worth remembering that the API Gateway\ninvokes Lambda functions ___synchronously___:\n\n    http://docs.aws.amazon.com/lambda/latest/dg/lambda-services.html\n\nIn line with their many uses, Lambda functions can be invoked synchronously __and__ asynchronously;\nthis may well affect how they need to be coded (in terms of retries, etc). If they are triggered via\nthe API Gateway, then they will be blocking calls.\n\nIf they are __only__ invoked via the API Gateway then there is no requirement for queues (DLQs,\netc).\n\n## Authentication\n\nAPI Gateway endpoints can be secured using AWS_IAM or NONE (i.e. completely open).\n\nFor more complicated scenarios there are custom authorizers:\n\n   http://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-use-lambda-authorizer.html\n\nCustom authorizers were announced\n[February 2016](http://aws.amazon.com/blogs/compute/introducing-custom-authorizers-in-amazon-api-gateway/).\n\nIt is also possible to restrict access using [VPCs](#networking).\n\n## Networking\n\nThe general recommendation is to NOT use VPCs:\n\n\u003e Don't put your Lambda function in a VPC unless you have to\n\n![VPC flowchart](images/VPC-flowchart4.png)\n\nBoth the flowchart and the quote are from:\n\n    http://docs.aws.amazon.com/lambda/latest/dg/best-practices.html#lambda-vpc\n\nAs the article states, VPCs add an extra layer of configuration. They will not help with cold starts\nnor will they reduce network latency (in fact they can be expected to make both worse). Also, they\nrequire Elastic Network Interfaces (or ENIs) for almost every cold start - and ENIs are not free.\nVPCS will also complicate scaling. They may be needed in rare situations but otherwise deliver\nlittle benefit.\n\n[Anecdotal reports suggest ENIs add 10 seconds to cold start times.]\n\n## Pricing\n\nAmazon API Gateway pricing:\n\n    http://aws.amazon.com/api-gateway/pricing/\n\n\u003e The API Gateway free tier includes one million API calls, one million messages, and 750,000 connection\n\u003e minutes per month for up to 12 months.\n\n## Reference\n\nSome useful links follow.\n\n#### AWS API Gateway\n\nAmazon API Gateway Documentation\n\n    http://docs.aws.amazon.com/apigateway/index.html\n\nAPI Gateway Mapping Template and Access Logging Variable Reference\n\n    http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html\n\nEnable API Caching to Enhance Responsiveness\n\n    http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-caching.html\n\n#### JSON Schema\n\nAPI Gateway models are defined with JSON Schema:\n\n    http://json-schema.org/\n\nUnderstanding JSON Schema:\n\n    http://json-schema.org/understanding-json-schema/index.html\n\n#### WebSockets\n\nAbout WebSocket APIs in API Gateway\n\n    http://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api-overview.html\n\n[WebSockets are not thought to be a good fit for serverless functions, which are stateless.]\n\n#### Postman\n\nCall an API with API Gateway Lambda Authorizers\n\n    http://docs.aws.amazon.com/apigateway/latest/developerguide/call-api-with-api-gateway-lambda-authorization.html\n\n[The article shows how to use [Postman](http://www.getpostman.com/) to test an API Gateway API.]\n\n## To Do\n\n- [x] Test with predefined Swagger\n- [x] Investigate if VPCs are a good fit for serverless\n- [x] Investigate if it is possible to export Swagger for a defined API Gateway\n- [x] Investigate AWS API Gateway Caching\n- [x] Investigate AWS X-Ray\n- [x] Investigate Google Cloud Endpoints\n- [ ] Investigate [Apigee Edge](http://cloud.google.com/apigee/api-management/)\n- [ ] Test with WebSockets\n- [ ] More testing\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmramshaw%2Fapi-gateways","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmramshaw%2Fapi-gateways","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmramshaw%2Fapi-gateways/lists"}