HTTP-ILP: Paid API Calls with Interledger

Imagine you’ve created a great service, and you want to expose it as an API. You’ve put a lot of work in, so you want to make it into a stream of income.

Until now, the only way to monetize your API has been to require users to enter payment information. But users hate doing that, so maybe you start with a trial version. Or you charge a subscription.

Either way, most of your time is going to be spent worrying about the business model, instead of working on your actual product.

HTTP-ILP allows you to charge for an API using Interledger. Unlike ordinary paid APIs, HTTP-ILP doesn’t require users to register or create API keys. Interledger payments are fast and small enough for users to pay with every API call.

Thanks to the javascript libraries that we’ve created, payment-enabling an API is a two-line change.

This tutorial will show you how to:

• Upload data with a paid API
• Write a paid API

Prerequisites

This tutorial assumes that you’re running Moneyd on your computer, and that it’s connected to the Interledger testnet. You can read about how to set up Moneyd here.

If you’re not yet set up, it should only take a minute. You don’t need to register any accounts or buy any cryptocurrency to use the Interledger testnet.

Upload Data with a Paid API

In order to interact with paid APIs, we’ll be using ILP Curl. ILP Curl is a command-line tool similar to cURL, which also connects to Moneyd to provide Interledger payments.

Make sure that you have permissions to install node modules globally.

npm install -g ilp-curl
ilp-curl -X POST https://unhash.ilp-test.com --data "Hello World"

If your Moneyd is configured correctly, you’ll receive a response that looks like:

{
  "url":"https://unhash.ilp-test.com/a591a6d40bf42040...",
  "digest":"a591a6d40bf420404a011..."
}

You just used “Unhash,” which is an extremely simple paid API for hosting files. It uses content-addressed storage to reference files by the hash of their contents. If you query the url that you got, it will return the string Hello World.

You can try the same query with some other parameters.

• Try reading ilp-curl --help to see how you can upload a whole file.
• Try uploading a file with curl instead of ilp-curl and see what happens.

Write a Paid API

“Unhash” is just an endpoint that uses HTTP-ILP. You didn’t need any Unhash-specific tools to access it, just ILP-Curl.

You can also write an API that can be accessed with ILP-Curl. The Koa-ILP module makes it trivial to payment-enable any Koa application in Node.js.

First, set up a project for your paid API:

mkdir my-paid-api
cd my-paid-api
npm init
npm install --save koa koa-router koa-ilp ilp-plugin
vim index.js # open this in your editor of choice

Then add the following code to index.js:

const Koa = require('koa')
const router = require('koa-router')()
const app = new Koa()

const KoaIlp = require('koa-ilp')
const plugin = require('ilp-plugin')()
const ilp = new KoaIlp({ plugin })

router.get('/', ilp.paid({ price: 100 }), async ctx => {
  ctx.body = 'Hello World!'
})

app
  .use(router.routes())
  .use(router.allowedMethods())
  .listen(8080)

We used ilp-plugin to get a connection to our local Moneyd instance. Then we gave the “plugin” to Koa-ILP so that it can receive payments. Finally, we added our ilp.paid middleware to the endpoint that we wanted to charge for.

Start your new application with:

DEBUG=ilp* node index.js

Then, in a separate terminal, call your API using ILP-Curl:

ilp-curl -X GET http://localhost:8080/

You’ll get a response of Hello World!. Congratulations, you just made your first paid API!

With this technique, you can payment enable anything. You could wrap an existing API in a flat price, or you could create a product that wouldn’t have been viable otherwise, like Unhash.

If you go out and make something cool, tell us about it on our Gitter!