Build versioned API routing and admission policies

Application background

Many internal teams expose HTTP APIs, and clients need a common address to reach them. An API gateway receives a request, checks shared entry rules and forwards it to the selected service. For example, /orders/17 goes to the order service.

The gateway needs a table of routes and configuration versions. A bad update could otherwise break many services at once. Verifying a caller's identity at the gateway also does not decide which individual orders that caller may read.

Example walkthrough

Authentication establishes who the caller is. Resource authorization decides whether that caller may perform this operation on this particular record.

Your assignment

Deliver: Build a versioned route configuration with validation, activation and rollback. Trace one request to show what the gateway checks and what the destination service still decides.

Required behavior: The gateway verifies identity and routes using a versioned configuration snapshot. Backends authorize requested objects. The gateway adds at most 15 ms p99 overhead under the stated load and propagates a request deadline and trace context.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/api_gateway_platform.py

Supplied file: examples/architecture-starts/api_gateway_platform.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for api-gateway-platform. No AWS resources are created."""
active={'version':1,'routes':{'/orders':'orders-v1'}}
def activate(candidate):
    if not candidate.get('routes') or any(not p.startswith('/') for p in candidate['routes']): return 'rejected; keep version '+str(active['version'])
    active.clear(); active.update(candidate); return 'active version '+str(active['version'])
print(activate({'version':2,'routes':{'orders':'broken'}}))
print(activate({'version':3,'routes':{'/orders':'orders-v2'}}))
print(active)

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

rejected; keep version 1
active version 3
{'version': 3, 'routes': {'/orders': 'orders-v2'}}

Set up your implementation workspace

Create work/api-gateway-platform/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Implement one protected route

Validate issuer, audience, signature and token expiry. Strip untrusted identity headers before adding trusted context. Protect the gateway-to-backend network/authentication boundary so a caller cannot bypass the gateway and forge context.

2. Bound each request

Propagate an absolute remaining deadline and use bounded connections, body sizes and queueing. Do not retry non-idempotent backend operations merely because the gateway timed out. Measure authentication, routing and upstream waiting separately.

3. Ship configuration as an atomic snapshot

Validate routes, auth rules and timeout bounds before activation. A custom proxy can consume AppConfig. AppConfig does not automatically reprogram API Gateway. Instances retain the last valid snapshot on parse failure and report the exact applied version.

4. Roll out by limited traffic scope

Start with a subset of instances or routes, compare errors/latency, and restore the prior snapshot on an observed regression. Keep configuration change ownership and emergency access explicit without moving object authorization into a universal gateway rule.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

This is a custom proxy platform behind an ALB. Managed API Gateway is an alternative when its routing, authentication and quota features fit. Its control plane and deployment model are different from an AppConfig-driven proxy.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Let teams own routes without editing the whole gateway

A typo in one team's route should not remove another team's checkout endpoint. Moving edits into a UI does not by itself reduce the blast radius.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Separate the control plane, which accepts route changes, from the data plane, which serves requests. Validate ownership, route conflicts, target permissions and retry policy before producing an immutable configuration revision. Gateway instances acknowledge the revision they loaded and retain the last known good one if the control plane fails. Roll out by gateway cohort and keep old revision compatibility for in-flight requests. On AWS, an ECS gateway and a versioned configuration store can demonstrate this separation.

Walk through the result. Let team A change /a while team B serves /b. Submit a wildcard from A that would capture /b and show rejection. Then make A's accepted revision fail on a small cohort and restore the old revision without changing B's routes. Supply configuration IDs and per-route outcomes.

Offer team-managed routing. Define ownership namespaces, validation and blast-radius limits so a team can change its service without editing a global configuration file that can disable unrelated routes.