When your API is the contract

@switzerly

data

About me

- So many REST Fests

- Civic hacking

- APIs

- Healthcare

- www.civicunrest.com

- Engineering @ US Digital Service

@switzerly

API #allthethings

@switzerly

Civic Tech

@switzerly

Local Government API

@switzerly

Nonprofit API

@switzerly

🤔

@switzerly

Questions:

How do I API this data?
What even is this data?
How do we make this data usable?
What do the users need?

@switzerly

Do we even need an API?

@switzerly

$ docker-compose up -e ORIGIN_REPO="switzersc/food-data"

$ curl http://dockerip:4567/resources?dedupe=bustype

throw data into github repo
pull/build docker image

API-in-a-box

Phase 1: How do I make an API?

@switzerly

API

@switzerly

The problem:

curl http://dockerip:4567/resources

@switzerly

{
    "collection" :
        "href" : "http://dockerip:4567/resources/",
        "items" : [ 
            {
                "href" : "http://dockerip:4567/resources/8903493",
                "data" : [
                  {"name" : "name", "value" : "Bob's Convenience Store"},
                  {"name" : "lat", "value" : "33.760094"},
                  {"name" : "lng", "value" : "-84.386037"},
                  {"name" : "bustype", "value" : "convenience"},
                  {"name" : "FILE_SOURCE", "value" : "GA_EBT.csv"}
                ]
              }
        ],
        "queries" : [
            {"rel":"search", "href":"http://dockerip:4567/resources/search", "prompt":"Search",
                "data" : [
                    {"name" : "name", "value" : ""},
                    {"name" : "lat", "value" : ""},
                    {"name" : "lng", "value" : ""},
                    {"name" : "bustype", "value" : ""},
                    {"name" : "FILE_SOURCE", "value": ""},
                    {"name" : "dedupe", "value" : ""}
                ]
            }
        ]
}

Hypermedia: Collection+JSON

@switzerly

The user has to know the semantics.

@switzerly

The user has to be willing and able

to wrangle the data.

@switzerly

Case study: Miami

@switzerly

Before we can API...

we must ETL.

@switzerly

Extract:
- Get data out of a SQL Server in a custom structure
Transform:
- Apply the semantics!
- Convert the data into the Health and Human Services Data Spec (HSDS) format
- Do some data cleanup
Load:
- Make this data usable on our multiple platforms
- Package this data in an easily transferrable way: datapackage and ZIP

@switzerly

datapackage.zip

Data source(s)

ETL

API

Web UI

Docs

@switzerly

Benefits

Self-describing data
Dataset is source of truth
Dataset can be hosted or not
Data can be transported easily
Clients and tools can be any language, stack, budget, etc, as long as they can load a zip file and understand datapackage.json
Can generate self-documenting, self-describing APIs easily with shared semantics, to meet different use cases

@switzerly

What's next?

auto-generate OpenAPI specs and other API definitions from the datapackage.json
explore QRI and content-addressing for datapackage: https://qri.io/
explore implementing JSON-LD and other linked data paradigms for the dataset and generated APIs
more iterations!

@switzerly

Thanks!

@switzerly