Effortless SDKs

The Data Problem

So you want to build a Spotify app? Or maybe take payments using the Stripe API? Or maybe you only want to talk with your back end. All of these require writing HTTP requests, writing encoders and decoders. It’s a pain. If you’re looking to use a large API like Square’s this can mean tens or hundreds of endpoints with a variety of types to pass in. Do you really want to write up all of that wiring? I don’t! What are we to do?

An Answer

Why not generate it all! Very handily each of these services, and many more, provide an Open API Spec that defines all of their endpoints and how you use them. Quick aside, this spec used to be known as Swagger so if you ever see that name you’re likely looking at an older version. Now that we have a structured way of talking to a large variety of APIs, how do we use it?

This is why I’ve written the Elm package wolfadex/elm-open-api. This package allows us to parse these specs and use them inside any Elm app. That’s step one down, and we’ll come back to it more later, but how does this help us write encoders, decoders, and make requests? That’s where my Node package comes in, elm-open-api! This package is a CLI tool for taking an Open API Spec (OAS) and transforming it into an Elm module. It generates your encoders, decoders, and the HTTP requests (both Cmds and Tasks) for every endpoint and data structure. Now instead of spending your time wiring it all up, you can spend if focusing on building your app. For an example, I’ve forked the Elm Land RealWorld app to use elm-open-api.

Beyond HTTP

Is that all? Far from it. An OAS is useful for far more than making requests. It just so happens that it also contains documentation information. Now we can parse an OAS and generate docs, maybe even using elm-pages to statically render (note: this is how Square generates their docs).

Surely that’s it? Not quite! There’s one more project I have in the works as a follow-up. Internally, OAS uses JSON Schema to define the request bodies, responses, and query params. Additionally there’s a small schema, UI Schema, that can be combined with JSON Schema to define forms meaning… form generation! This work is still a little ways off but it’s perfectly practical.

What’s Next

This is a lot to think about, and to be honest there’s a lot of work still to do, but I’m happy to have an initial version out as this has been in the works for 2 years! There’s still a lot of improvements to be made to the OAS Elm package like supporting older versions and handling of custom fields. There’s also work to be done on the Node package to generate better error handling. I have some crazier ideas involving OAS and codegen as well, though I’m saving those for another day 😉