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

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