Getting Started with API Gateway - Agent

Create a local and hosted project

Run:

Code
npx create-zuplo-api@latest example-project
cd example-project

When prompted, choose Yes to create a matching Portal project, complete sign-in, and select your Zuplo account. Select the coding agent you use when asked. The CLI creates a project in the Portal and links your local example-project directory to its working copy. The hosted project stores the API key consumers and receives your deployment. If the CLI reports that project creation failed, run npx zuplo project create --name example-project from this directory. If linking failed, or after creating the hosted project, run npx zuplo link and select its working copy before continuing.

Start the gateway

Code
npm run dev

Leave this running. The agent edits config/ and modules/, and the dev server hot-reloads.

Copy the prompt

Code
Read this project's agent instructions and the bundled docs in node_modules/zuplo/docs before writing code.

Build a Zuplo API gateway in this project:
1. Keep the default todo routes in config/routes.oas.json, but forward them to ${env.BASE_URL} and add BASE_URL=https://echo.zuplo.io to .env.zuplo.
2. Add the rate-limiting inbound policy (rateLimitBy: ip, 2 requests / 1 minute) to every route.
3. Add the api-key-inbound policy to every route, ordered before rate limiting.
4. Make rate limiting dynamic: create modules/rate-limit.ts exporting rateLimit() that returns 1000 req/min for user.data.customerType === "premium", 5 for "free", 30 otherwise, and switch the policy to rateLimitBy: "function".
5. Use the already-running dev server to verify with curl that GET /todos returns 401 without a key. I will create the free and premium keys in the Portal afterward; leave key-based tests for me.

Explain each config change in one line and stop before pushing to git.

Review what it changed

Expect edits to config/routes.oas.json, config/policies.json, a new modules/rate-limit.ts, and .env.zuplo. Open the local Route Designer at http://localhost:9100 to see the policies on each route.

Create two consumers

In the portal, open Services › API Keys › Consumers › Create Consumer. Create free-consumer with metadata { "customerType": "free" } and premium-consumer with { "customerType": "premium" }.

Test both limits

Code
# no key -> 401
curl -i http://localhost:9000/todos

# free key -> 429 on the 6th request within one minute
for i in 1 2 3 4 5 6; do
  curl -i http://localhost:9000/todos \
    --header 'Authorization: Bearer FREE_CONSUMER_KEY'
done

# premium key -> 1000 requests per minute
curl http://localhost:9000/todos \
  --header 'Authorization: Bearer PREMIUM_CONSUMER_KEY'

Replace FREE_CONSUMER_KEY and PREMIUM_CONSUMER_KEY with the keys from the Portal. The premium request should succeed; its limit is 1000 requests per minute, so a single request doesn't test the threshold.

Ask the agent to push

Code
Commit everything, create an empty GitHub repo called example-project with gh, add it as origin and push main.

Connect the repository in Zuplo

Code
npx zuplo info

Open the source-control link from the output, or Settings › Source Control in the portal. Click Connect to GitHub, then Connect on your repository. Zuplo deploys main immediately. Run zuplo info again to confirm.