api gateway: the front door nobody explained to you

a semi-deep dive into aws api gateway and how it works

okay so if you read my lambda post you might remember i kept mentioning this thing called api gateway and then told you basically nothing about it. so here we are. every api gateway explainer opens with the exact same sentence, “amazon api gateway is a fully managed service that makes it easy to create, publish, maintain, monitor and secure apis at any scale”, and then i close the tab yet again because i still have no idea what it actually does. so im not doing that.

quick credentials so you dont think im making this up… im a software engineer at AWS and since im on a frontend team i theoretically should have at least an idea of what api gateway is, so heres what i do know.

in simple terms api gateway is the front door to your backend. its the bit that sits between the public internet and your actual code. every request from the outside world hits api gateway first, and api gateway goes “okay who is this, are they allowed in, are they sending me way too many requests, and where is this request even supposed to go” and only then does it hand the request off to whatever is doing the real work behind it.

normally if you wanted to expose your code to the internet you would have to build all of that yourself. youd write the code that checks if someone is logged in, the code that stops one guy from spamming you with 10,000 requests a second and taking the whole thing down, the code that checks the incoming data isnt complete garbage, the code that sends /users to one place and /orders to another, the logging, the api keys for your customers… that is a lot of code…and none of that is the actual thing you set out to build. its all just door management. api gateway is the door management. you point it at your backend, you tell it the rules, and it handles everything that happens before a request is allowed to reach your code.

so what actually happens when a request comes in. someone out on the internet sends a GET request to your-api.com/users. api gateway catches it at the matching route. first it checks the authorizer(more on that below), are you even allowed to do this? if not you get a 401 and you never reach the backend at all. then it checks throttling, are we over the rate limit? if yes you get a 429. then it can validate the request, did you actually send me the fields im expecting? if the request survives all of that, api gateway forwards it on to the integration (the thing that does the work - more on that shortly), waits for the response, potentially reshapes it, and sends it back to the caller. all the bouncer stuff happens before your code ever runs. as you can see it handles a ton of things that you’d have to manually do yourself.

the way you set it up is you define routes, which are literally just a method plus a path. GET /users, POST /users, GET /users/{id}, DELETE /orders/{id} and so on. each route points at an integration, which is just a fancy word for “the thing that handles this route” and the integration is usually one of three things. one, a lambda function, by far the most common, this is the lambda + api gateway combo i mentioned in the last post. two, some http endpoint you already have running, a server on ec2, a container, literally any url, and api gateway just forwards the request straight through to it. three, another AWS service directly with no code in between at all, you can have api gateway drop the request straight into an SQS queue or write it into dynamodb without a single line of code.

okay so the whole point of this thing is the stuff it does for you that you would otherwise have to build by hand. auth is the big one, you attach an authorizer to a route and api gateway checks every single caller before letting them in, could be IAM, could be a cognito user pool, or could be a lambda authorizer where you write your own custom “is this token legit” logic. then theres throttling, you set a rate limit and api gateway enforces it so one client cant accidentally (or on purpose) take your backend down. theres api keys and usage plans, so if youre exposing an api to other people you can hand out keys and say this key gets 1000 requests a day and this one gets a million. and theres request validation, caching, CORS, custom domains and logging to cloudwatch, all of which you configure instead of code yourself.

now the one thing that confuses literally everyone. when you go to create an api, aws asks do you want a REST api or an HTTP api, and the names are useless because both of them are for building HTTP apis. heres the actual difference. REST apis are the older, fully loaded option with every feature (api keys, usage plans, request validation, caching, etc). HTTP apis are the newer, stripped down option, fewer features but theyre cheaper and a bit faster. my rule of thumb is just start with an HTTP api and only reach for a REST api if you specifically need a feature it has. theres also WebSocket apis for real-time two-way stuff like chat apps but i havent got the chance to use those yet.

for the ceo’s reading this that care about pricing luckily the model is pretty simple, you basically pay per request. a few dollars per million requests, and HTTP apis are even cheaper than REST apis for the same traffic. theres also a free tier that covers a million calls a month for your first year which is way more than enough to mess around and build something real.

as usual there are a couple of limits it helps to know when youre weighing trade-offs. api gateway has roughly a 29 second timeout on integrations(oddly specific i know), so if your backend takes longer than that api gateway just gives up and returns an error, meaning its not built for long running jobs. it has a max payload size (10MB on REST apis) so its not for uploading huge files, for that youd hand out an s3 upload url instead(more on that in a future article). and theres a default account level rate limit (10,000 requests a second) which you can ask aws to raise if you ever get that big.(one day…)

honestly the fastest way to actually get this is to go build the tiny version. open the aws console, make a lambda with the 3 line handler from my last post, then create an HTTP api, add one route, point it at the lambda, and hit the url it gives you in your browser. then watch your own request travel internet → api gateway → lambda → back to your browser and thats genuinely it.this is a great tutorial if you get stuck.

anyway thats api gateway.it decides who gets in, how often, and where they go, and then it hands the request off to your real code. everything else like the authorizers, the throttling, REST vs HTTP, the pricing, is just detail layered on top of that one idea. if you remember nothing else from this remember “front door” and youre 90% of the way there.

if you learnt something subscribe! xD