Building a JSON API Using Jupyter Notebooks in Under 5 Minutes

In the post Making a Simple Database to Act as a Lookup for the ONS Register of Geographic Codes, I idly pondered creating a simple API for looking up ONS geographic codes.

Popping out to the shop for a pint of milk, I recalled one of the many things on my to do list was too look at the Jupyter Kernel Gateway, as described in the IBM Emerging Technologies blogpost on Jupyter Notebooks as RESTful Microservices.

The kernel_gateway project looks to be active – install it using something like pip3 install jupyter_kernel_gateway – and set up a notebook, such as simpleAPI.ipynb (the following code blocks represent separate code cells).

Import some helper packages and connect the geographic codes db I created in the previous post.

import json
import pandas as pd
import sqlite3
con = sqlite3.connect("onsgeocodes.sqlite")

Create a placeholder for the global REQUEST object that will be created when the API is invoked:

REQUEST = json.dumps({
'path' : {},
'args' : {}
})

Now let’s define the API.

For example, suppose I want to return some information about a particular code:

# GET /ons/:code
request = json.loads(REQUEST)
code = request['path'].get('code')

q='SELECT * FROM codelist WHERE "GEOGCD"="{code}"'.format(code=code)
print('{"codes":%s}' % pd.read_sql_query(q, con).to_json(orient='records'))

Or suppose I want to look up what current codes might exist that partially match a particular place name:

# GET /ons/current/:name
request = json.loads(REQUEST)
name = request['path'].get('name')

q='''
SELECT * FROM codelist JOIN metadata
WHERE "GEOGNM"="{name}" AND codeAbbrv=sheet AND codelist.STATUS="live"
'''.format(name=name)

print('{"codes":%s}' % pd.read_sql_query(q, con).to_json(orient='records'))

On the command line in the same directory as the notebook (for example, SimpleAPI.ipynb), I can now run the command:

jupyter kernelgateway --KernelGatewayApp.api='kernel_gateway.notebook_http' --KernelGatewayApp.seed_uri='./SimpleAPI.ipynb'

to start the server.

And as if by magic, an API appears:

The original blogpost also describes a simple docker container for running the API. Which makes me thing: this is so easy… And using something like LaunchBot, it’d be easy enough to have a simple manager for local API servers running on a personal desktop?

Here’s the complete notebook.