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
  1. throw data into github repo
  2. pull/build docker image
  3.  
  4.  

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

@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

@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

Made with Slides.com