Getting Started with Zuplo, the Modern API Gateway

API Gateways provide all sorts of really helpful functionality for APIs developers, covering things like rate limiting, authentication, network caching, and some of the newer ones will support server-side validation based on OpenAPI and/or JSON Schema.

This is all awesome, but it usually happens through some web interface that's a long way away from the source code and gets easily confused when pull requests change things. I don't want to have to ask someone on the Infra team to remember to add my new endpoint to the API Gateway when they get back from holiday. I don't want to copy and paste the updated OpenAPI into a text box on a web interface every few weeks. That should all be powered by Git!

Thankfully this is exactly what Zuplo is about. Zuplo's creators set out to make it feel native to developers, who increasingly expect to be able to do everything through their existing GitOps workflows, and are becoming less and less interested in configuring weird XML via SSH on servers they forgot how to work with.

As you can tell I'm not a infrastructure person, but I'm going to have a go at setting up Zuplo, to see if a bog-standard software engineer + API designer/developer can get, and how easy it is.

Sample Application

Of course any guide needs a sample app, and I've been writing a Widgets API in Laravel PHP to get us started. You can create, read, update, delete, and see a list of widgets. Nothing wildly exciting but no doubt similar enough to any Laravel, Rails, NextJS, FastAPI, etc application you've ever built.

Let's have a quick look at the API here.

$ php artisan serve

   INFO  Server running on [http://127.0.0.1:8000].

The API will show us what resources are available, and the main one there is the list of widgets.

$ http GET http://localhost:8000/api/widgets

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Cache-Control: no-cache, private
Connection: close
Content-Type: application/json
Host: localhost:8000
X-Powered-By: PHP/8.3.1
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

{
    "data": [
        {
            "created_at": "2024-01-05T11:00:49.000000Z",
            "description": "A memory-altering device utilizing advanced neural stimulation. Designed for use by government agencies, it selectively erases specific memories, ensuring the confidentiality of classified information.",
            "id": 1,
            "links": {
                "item": "http://localhost:8000/api/widgets/1"
            },
            "name": "Neuralyzer",
            "updated_at": "2024-01-05T11:00:49.000000Z"
        },
        {
            "created_at": "2024-01-05T11:01:40.000000Z",
            "description": "A molecular assembler that rearranges atoms to create objects, food, or even living organisms on demand. The replicator has revolutionized manufacturing, reducing waste and providing unprecedented convenience.",
            "id": 2,
            "links": {
                "item": "http://localhost:8000/api/widgets/2"
            },
            "name": "Replicator",
            "updated_at": "2024-01-05T11:01:40.000000Z"
        }
    ],
    "links": {
        "self": "http://localhost:8000/api/widgets"
    }
}

This application already has rate limiting using the non-standard X-RateLimit-Limit headers, and there's some authentication logic I've not yet turned on, but I want to use Zuplo to do all of this.

Why? Having each API handle its own rate limiting logic is prone to issues, as it's on the API to try and detect complex shenanigans, and the implementations of rate limiting across different APIs should be standardized not unique to each API.

The same goes for authentication. If I try and handle all of the API Key / OAuth 2 logic in the application, not only will that end up with really inconsistent experiences as some APIs use Laravel Sanctum, and others use Rails Doorkeeper, but it also means I'll have to build a whole system for API clients to sign up and get their API tokens, and why bother when Zuplo can do that for me.

Starting the Zuplo Local Development Server

Before we go running off to the Zuplo website to worry about signing up or whatever, we can use the Zuplo development environment to speed things up.

$ cd ~/src/laravel-zuplo-demo

Now we want to create a new "project", which could be multiple APIs if we wanted it to be, but for now we're just going to make our project power one API and have it right in here with our API source code.

$ npm create zuplo-api@latest

? What do you want to name your project? widget-gateway

Zuplo will tell us exactly what to do next.

Scaffolding project in /Users/phil/src/laravel-zuplo-demo/widget-gateway...

Done. Now run:

  cd widget-gateway
  npm install
  npm run dev

Once that run last command has been run, the gateway will be up and running.

Started local development setup
Ctrl+C to exit

🚀 Zuplo Gateway: http://localhost:9000
📘 Route Designer: http://localhost:9100
⚙️  Loaded env files:
    - .env

Side-note: I had trouble here with the default ports already being in use, which according to lsof they were not. After scratching my head I figured just side-step the problem with npx zup dev --port 9910 --editor-port 9911, and that worked fine.

Configuring the API Gateway

The gateway is up and running, but we've not told it anything yet. It has no idea where the API is, so lets do that:

# widget-gateway/.env

BASE_URL=http://127.0.0.1:8000

That's the web server running on the php artisan serve command from earlier. Setting this lets the API gateway know where your API is, and we can use that later. Make sure to restart the local development server (run npm run dev again).

Now it needs to know what routes should exist, and there's a few things we can do but lets just make something work quickly. Open the Route Designer on whatever port its running on (default http://localhost:9100.)

local-route-designer.png

Click Add Route and enter something like this, just to get something running.

first-route-widget-collection.png

Right! Moment of truth. Let's try hitting the API gateway and getting the widget controller JSON again.

$ http GET http://localhost:9910/api/widgets

HTTP/1.1 200 OK
cache-control: no-cache, private
connection: close
content-encoding: gzip
content-type: application/json
host: 127.0.0.1:8000
vary: Accept-Encoding
x-powered-by: PHP/8.3.3
x-ratelimit-limit: 60
x-ratelimit-remaining: 59

{
    "data": [
        {
            "created_at": "2024-01-05T11:00:49.000000Z",
            "description": "A memory-altering device utilizing advanced neural stimulation. Designed for use by government agencies, it selectively erases specific memories, ensuring the confidentiality of classified information.",
            "id": 1,
            "links": {
                "item": "http://127.0.0.1:8000/api/widgets/1"
            },
            "name": "Neuralyzer",
            "updated_at": "2024-01-05T11:00:49.000000Z"
        },
        {
            "created_at": "2024-01-05T11:01:40.000000Z",
            "description": "A molecular assembler that rearranges atoms to create objects, food, or even living organisms on demand. The replicator has revolutionized manufacturing, reducing waste and providing unprecedented convenience.",
            "id": 2,
            "links": {
                "item": "http://127.0.0.1:8000/api/widgets/2"
            },
            "name": "Replicator",
            "updated_at": "2024-01-05T11:01:40.000000Z"
        }
    ],
    "links": {
        "self": "http://127.0.0.1:8000/api/widgets"
    }
}

Huzzah! Off to a good start, but… my application has not quite figured out it's running through a proxy yet, and its sending people to the original hostname not the new host name. In development this is the wrong port, but in production that'll be an internal hostname/IP vs the proper public host name.

Teach Laravel to use public links instead of "whatever server I think I am right now" links involves first setting the APP_ENV in your applications' .env file (not the gateway .env).

.env
APP_URL=http://localhost:9910

Interesting Laravel will not use the APP_URL for route() or url(), so I've had to update my app/Http/Resources/WidgetCollection.php to avoid those functions.

    public function toArray(Request $request): array
    {
        return [
            'data' => $this->collection->map(function ($widget) {
                return [
                    'id' => $widget->id,
                    'name' => $widget->name,
                    'description' => $widget->description,
                    'created_at' => $widget->created_at,
                    'updated_at' => $widget->updated_at,
                    'links' => [
                        'item' => sprintf("%s/api/widgets/%s", config('app.url'), $widget->id),
                    ],
                ];
            }),
            'links' => [
                'self' => sprintf("%s/api/widgets?page=%s", config('app.url'), $request->query('page', 1)),
            ],
        ];
    }

Now the gateway knows where the application is, and the application knows how to run inside the gateway, we need to get all the other endpoints working instead of just this test one.

We could sit down and spend however long entering all the routes manually like API Gateways of old, but thankfully this one is OpenAPI aware, and thankfully I have an OpenAPI document for this API!

Importing OpenAPI to Zuplo

TBC Any way to get this done in local route designer or do i need to publish then use the OpenAPI Merge on the cloud version?

DO NOT INCLUDE Notes to work in

Moving rate limiting out of app to the gateway
Move something off to an edge function, like the image uploads
Show off your fancy ass docs now

• Interesting things

Global rate limiting solves people changing region and getting more rates