API Evangelist

I am Kin Lane, the API Evangelist...

This is my work in partnership with Open Referral to move forward the Human Services Data Specification (HSDS), in conjunction with a definition for the Human Services Data API (HSDA). I've dedicated a portion of my time as the API Evangelist to help move forward the conversation about how we store, share, publish, and collaborate around human services data.

I was introduced to this work by Greg Bloom (@greggish) of Open Referral back in 2015 and 2016, and signed on as the technical lead by 2017. I'm invested in the projects success, and will invest as much time as I possibly can helping contribute to the data schema, API definition, tooling, and storytelling. I feel the project reflects the API potential, helping make our world work better for humans, not just something that tech startups do.

What Is The Human Services Data Specification

The vision of Open Referral is a world where everyone has access to — and the ability to effectively use — information about the resources that are available in their community.

The Human Service Data Specification (HSDS) is a data schema used to describe human services that are present in any city, state, or province. The schema is to provide a common way to descibe information, helping standardize how it can be stored, and shared in service of the Open Referral vision.

The Human Services Data API (HSDA) is an OpenAPI definition providing the technical details of an API which can provide access to data stored in the HSDS format. An API will open up human service systems and websites for integration with other systems, web and mobile applications--helping ensure everyone has access to, and the ability to put human services to work.

Human Service Providers & Implementations

This work is not about providing a single API. It is about developing a blueprint for deploying and managing many APIs. The schema and API definition is meant to provide a common blueprint that any government or human services organization can follow to design and deploy their own HSDS compliant API ensuring it will speak to any other HSDS compliant APIs--making human service websites and application potentially more interoperable.

I'm supporting Open Referral's vision of "a world where everyone has access to — and the ability to effectively use — information about the resources that are available in their community." Embracing the open web, and acknowledging that humans and other systems and applications will benefit from a common data schema, as well as API definition, when it comes to individual human services implementations, as well as interoperability, aggregation, and federation of data across potentially thousands of individual implementations.

The HSDA OpenAPI Definition

The Human Services Data Specification is leveraging the OpenAPI specification to define the surface area of the Human Services Data API (HSDA), providing a machine readable definition of the API, and the underlying schema that is used as part of both requests and responses. You will see the HSDA OpenAPI mentioned throughout the platform, providing YAML versions to define all aspecs of implementation.

The OpenAPI for HSDA is the central definition which can be used to generate server side code, as well as client side tooling. It can be used to generate APIs using some of the platforms listed below. The OpenAPI provides a common contract that all developers, vendors, and HSDA implementors can use to talk about HSDA.

We are working on moving the OpenAPI definition from version 2.0 to version 3.0 of the specification, but will continue supporting the current iterations alongside each other, as long it makes sense.

Vendors Serving The Community

This work is not ignoring the fact that there are already numerous software providers already supporting a variety of human services data solutons in use across 211, and other municipal and health care systems. We are actively working with the top vendors to help gather their feedback, and expertise in operating real world human service implementations, and incorporate in future versions of the specification.

We are currently taking the schema and API documentation from over five providers and including as part of the current schema and API release. We will be actively working with new providers as they approach Open Referral. Our goal is to work with as many of the leadings groups as we possibly can, and help ensure interoperability with all the major systems that are currently serving municpalities.

For the Human Services Data Specification to be successful it will need to have the buy-in of major commercial providers, making it an industry standard in use across open source and proprietary human services implementations worldwide.

A Demo Portal and API

An important part of moving the human services API specification forward for me was to have an actual working demo I could use to better understand what is possible from a technical perspective. Without a functional version of the API specification it is easy miss many of the finer details involved with deploying, managing, testing, monitoring, and generally operating an API in the real world.

I have developed a working demo API in PHP, using the Slim API framework, giving me a working API that I can change and keep in sync with each version of the API specification. The API prototype is available on Github, but it is not quite production ready, so use at your own risk. If you are going to fork make sure and ping me, as I probably have a more recent version available that I have not updated because of time.

I have also developed a working developer portal where I have published documentation for the API demo. Providing a visual reference for what is possible with HSDA, complete with active documentation that you can use to play with and see responses.

View Developer Portal

Deploy Human Services On Common Platform

Open Referral is platform agnostic. We are not invested in Human Service Data Specific (HSDS) compliant implementations running on any single platfrom, or vendor. Our mission is that any human services implementation can run anywhere, and these are the platforms we are currently targeting with implementations and projects.

Heroku

The original Ohana implementation of Open Referral runs on Heroku, and we are looking to develop additional implentations that will deploy and operate via the Heroku cloud platform, and even potentially connect with SalesForce along the way.

Amazon Web Services

The Human Services API prototype in PHP currently runs on Amazon leveraging EC2, S3, and RDS for the backend. We are looking to develop additional solutions that run on AWS, and leverage a variety of AWS solutions like Labmda, API Gateway, and more.

Azure

We have begun to explore what it would take to design, deploy, and manage human services API implementations on the Azure platform. We'd like to have a working prototype, as well as specific implementations on Azure that we can showcase and help support future efforts on the cloud provider.

Google

We have also begun explore what it would take to design, deploy, and manage human service API implementations on the Google platform. We are looking for investment, developers, and potential implementations that would benefit from running on the Google platform. There are a wealth of services available on the platform, that the communitiy can put to use when providing access to data and other resources.

If there is another platform you'd like to see a Human Services Data Specification (HSDS) implementation target, please let us know. We are considering investing in platforms like Salesforce, WordPress, and others, but we don't like to start new projects without some support from a real world implementation and partners.

Develop Open Tooling

In addition to the platform projects, and the PHP demo, we are regularly investing in new open source tools, as well has help seed and encourage new projects developed on top of the Human Services Data API (HDSA), helping service providers better serve their constituents.

Ohana

Ohana is the original implementation of the Human Services Data Specification (HSDS), which began as a Code for America project. The project is still an active open source project with a number of forks and implementations. Ohana is a Ruby implementation, that runs on Heroku, but can be deployed anywhere.

Open Referral Playground

An open source tool developed by Chris Spilio, for validating the Open Referral schema, providing a dynamic registry of resource types based on latest schema, a visualization of a resource schema - this includes fields, keys, types, formats, etc., download sample CSV templates of resources, and upload and validation of a sample CSV file. A great example of the Open Referral community in action.

Github

Link-SF

The Link-SF project was forked by Optimizely, and made to be HSDS compliant, decoupling the front-end from the backend, and leverage Github. I took it a step further and made the front-end run 100% on Github, making the project forkable and usable in any city.

Other HSDA Tooling Ideas

Don't let the existing project's in motion limit your imagination. The municipalities that put the HSDA specification to work can benefit from a wide range of tooling that supports the format. While we encourage the development of platform, server, and other applications. Here are some of other ideas that we'd like to see out there that might stimulate the communiteis imagination, and see get built.

Interactive Documentation

We are currently using Read the Docs, as well as OpenAPI and Swagger UI for documentation of the schema and API. We welcome new implementations that leverage the good looks of Read the Docs, but also combines with the machine readability and interactive nature of OpenAPI and Swagger UI.

Sample Data Sets

Open Referral is in need of sample data sets that can be easily uploaded or imported into test, demo, and playground editions of the HSDA specification. Helping create platforms that can be played with, explored, and teaching people about what is possible with as real as data as possible.

Disaster Coordination

With the recent hurricanes in Florida and Texas, there is a significant amount of momentum when it comes to developing websites, web and mobile applications that can assist people in a time of need. Take a look at some of what has been developed already, and spend some time thinking what might help folks in the future.

Schema Validator

Ensuring that organizations, municipalities, and vendors are all speaking the same language is pretty critical to all of this working. The need for schema validation in a variety of languages, and platforms would help folks make sure their schema is compliant. The OpenAPI for HSDA has a JSON schema portion of the specification, which can be used to validate API requests and responses.

If there is an idea you'd like to see developed, feel free to reach out and I am happy to add to the list. We are looking to learn from existing human services implementations and understand what is needed on the ground.

Supporting Projects

HSDA is an API specification for managing a core set of resource (organizations, locations, and services), but there are a handful of other projects that add to the work that has is going around HSDA. These are the additional specification in prgoress, hoping to provide a buffet of services that any government, or organization can deploy.

HSDA Search

A project to develop search capabilities on top of HSDA implementations providing advanced capabilities for searching across all resources, for a wide variety of applications.

HSDA Bulk

A project dedicated to supporting bulk level operations around human services data, handling large adding, updating, and migrating of data. Including the usage of jobs to help reduce the load on core HSDA systems.

HSDA Taxonomy

A separate project for managing taxonomy related HSDA data, including AIRS, and Open Eligibility, but also allowing for custom taxnomy. Supports the browsing and searching of HSDA data using supported taxonomy.

HSDA Orchestration

A project for supporting the orchestration of HSDA data, including supporting of events, webhooks, and other features allowing HSDA implementations to push and pull data based upon a schedule, and events.

HSDA Meta

A project for handling the underlying logging and tracking of each API call made to any HSDA implementation. The HSDA Meta service can work with other systems to keep track of what happens on the platform, and leverage as a transaction system for triggering, rolling forward, and rolling backwards anything that occurs.

HSDA Management

A project for handling the management and access of HSDA implementations, providing a basic API management layer that handles access, and permissions for working with any HSDA API.

HSDA Utility

A project for handling all utility APIs involved with working with HSDA services and data. Currently providing service and path management, as well as validation of schema and APIs.

While these are potential HSDA projects, they are moving forward as separate services, that are designed to compliment, and augment a core set of HSDA implementations. They are versioned, and managed independently, allowing them to be deployed, scaled, and managed indepently of core HSDA implementations.

Define A Revenue Layer

One area I study as the API Evangelist is around the monetization, and access plans of leading API providers--studying how they are generating revenue around API consumption and even partnerships. I'm looking to extend this work to the human services industry, helping providers generate much needed revenue from their hard work, while still serving their consistuents. Here is an aggregation of all my stories regarding monetization of public data, and how this applies to my Open Referral work.

Should the Government Subsidize and Profit from Data Markets

Some of my original thoughts around the government generating revenue using public data, breaking from the curent thoughts that all public data should just be freely available for anyone to download and use in a commercial capacity.

Setting a Precedent When Charging for High Volume Access to Government APIs

Continuing my work to help the federal government think about generating revenue using public data and APIs. This time it was specifically regarding the Recreational Information Database (RIDB), and how the Department of Interior, and Forest Service can rethink digital resources alonngside how they generate revenue from other physical government resources.

Thinking About The Monetization Layer For Public Data

This is an essay I wrote doing a deep dive on the subject. I'm currently reworking this as a blueprint for how I am approaching monetization around human services data. It will become the basis for some future discussions I am facilitating around helping 211 and human service providers generate sensible and fair revenue around their operations--helping them stay available, and offering their consituents a valuable service.

Taxation On Public Data Via The API Management Layer

Continuing my thoughts on generating revenue from public data, I am actually exploring how the future of tax revenue at the municipal, state, or federal level can be conducted using APIs, and modern approaches to API management. This is all very new thoughts, but I'm looking to keep the conversation, preparing for the future of digital government.

We are just getting started with the discussions around how human service providers can generate revenue using the public data they manage, while also acknowledging other commercial vendors also generate sensible and fair revenue by providing products, services, and tooling to providers. If you have an experience and thoughts to share, feel free to get involved--we'd love to hear your thoughts.

Tell Stories

An essential part of all of this is telling stories about the schema, the specification, and the vendors and providers who are putting it to use. Stories need to be told of the conversaitons going on, the tools being built, and the impact being made on the ground in cities. Withtout this storytelling, nobody will know what is happening, and able to get involved and help move the specification forward.

We are telling the story of this project on the Open Referral Blog, on API Evangelist, and I have syndicated some of the stories here for easier access and review by new folks. If you have a human services story you would like to see told, feel free to reach out to submit a Github issue here, and I will get back to you about the best possible way to tell the story.

Read All The Stories

Get Involved

The Human Services Data and API Specifications are a community project. We need help defining the specification, as well as building tooling on top of the specification. There are endless projects that could be developed on the specification, but there are never enough people and resources to make them happen.

You can get involved with the data schema specification within it's Github repository, and the API specification in it's Github repository. The rest of the conversation is occurring on the Open Referral Google Group and the Slack channel. You can also visit the Open Referral site to learn more, and reach out directly to Greg and the rest of the organization.

Some Final Thoughts

Everytime I work on the Open Referral project I use this page as my start page. I will be updating it regularly as I have more information about the work that is going on. I will syndicate blog posts, and link up other Github repositories and projects as they become available--so return often, and feel free to bookmark this page.

Open Referral is Greg's passion, something that is contagious, and help contribute to it becoming my passion. I can't think of a more important API to be working on in today's political climate. We need to be investing in our communities at the local level, and a human services API can help bring folks together, delivering a common approach to helping people find the human services they need to get through the day.

Thanks for tuning in, and let me know how I can help get you plugged into what we are doing.