PicoFun: API Client Generator
There is little fun in writing boilerplate code. Learn how you can use PicoFun to generate your API client Lambda functions.
Building integrations and workflows is often a repetitve and error prone task. You start by identifying the endpoints you need to call. Before writing the client, you have to wade through sometimes poorly written docs. Then it is time to find and fix bugs, before eventually launching it. As we approach the end of 2024, there needs to be an easier way.
Code Generation
Over the last couple of years there’s been a lot of hype around the potential of GenAI. Unfortunately we aren’t there yet. Today you can't describe what you want and reliably get well written code that works first time. There is still a lot of back and forth with the bot before a human has to finish polishing the “code”.
This doesn’t mean we can’t generate code using other means. Enter PicoFun, a python based tool for generating API clients from an Open API v3 / Swagger spec file. The spec file can be in JSON or YAML format. It can be a local file or a URL.
PicoFun works with a handful of endpoints like the ubiquitous pet store example. It also works with a moster like the GitHub REST API v3 that weighs in at close to 1000 endpoints. Pretty much anything in between also works.
PicoFun generates clients as individual AWS Lambda functions for each endpoint. These Lambda Functions are then used in AWS Step Functions.
PicoFun not only generates the Lambda functions. It also provides the Terraform code needed to deploy them.
Templates drive the code generation. This means a developer can override the defaults with their own configuration. The templates are fast. On a decently spec’d laptop PicoFun generates 20-25 functions per second.
Customising Integrations
PicoFun is useful straight out of the box. That doesn’t mean it will work for all use cases. That’s why it includes overridable templates and configuration to change the behaviour of the generator.
In 2024, in a perfect world, API authentication would be a solved problem where there is one standard pattern. This isn’t the case.
By default, PicoFun makes unauthenticated requests to APIs. This is fine if you want to check the weather or a stock price. It doesn’t work if you want to update data in a SaaS app. PicoFun supports custom authentication handlers to solve this problem.
An authentication handler could fetch credentials from SSM Parameter Store and inject a Basic Authentication header into a request. Another could perform the 3 legged oAuth dance. The authentication handler is pluggable, so it should handle almost any exotic auth system.
PicoFun also exposes a post processing handler. This allows developers to modify the response before returning it.
Build Time vs Runtime
While the code generator isn’t a lot of code, bundling it into the lambda functions adds unnecessary bloat. That’s why I created PicoRun - the small runtime library. PicoRun is a lightweight wrapper around the Requests package.
PicoFun generates a common lambda layer with all the dependencies included. This keeps the lambda packages small and speeds up deployment.
Example Project
While documentation is useful, seeing a working example can save new users a lot of time. That’s why I created the Zendesk example. This is a complete working example.
Deploying the example project only takes a few steps. Copy the contents of the example project into a new git repo hosted on GitHub. Update the configuration to match your environment. Add the OIDC role ARN as a repo level environment variable. Now you should be right to deploy it. The initial deployment takes around an hour. Later updates are usually a lot quicker.
The Future
When I get time, I want to incorporate Pydantic models into the generator. This will allow validation of input and the upstream responses. I plan to use Koudai Aono's data model generator for this.
Over time I want to build out a public collection of ready to run PicoFun projects. These will be integrations with well known SaaS apps. Teams can grab it and deploy it into their AWS environment using the GitHub Actions pipeline.
Other than that, who knows 🤷♂️. Tell me what you’d like to see included in PicoFun.
Need Help?
If you want to adopt Proactive Ops, but you're not sure where to start, get in touch! I am happy to help get you.
Proactive Ops is produced on the unceeded territory of the Ngunnawal people. We acknowledge the Traditional Owners and pay respect to Elders past and present.