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 began this work with 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.

View API Specification

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.

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.

Focus On Platform Projects

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.

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 prototype 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 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 the working API prototype. The API portal runs 100% on Github, using Github Pages as the host, and the site using Jekyll as it's CMS. The portal is meant to be forked by any single API implementation, and converted into a custom portal. The portal intentionally uses Twitter Bootstrap, so that anyone can easily customize, while keeping things following a common standard. We will work on documenting the process when we have the time and resources.

View Developer Portal

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), help service providers better serve their consistuents.

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

Human Services Jekyll

This is a prototype for running a Human Services Data API (HSDA) 100% on Github, using Github Pages, and Jekyll as the content and data management system. It is an ongoing work in progress, but would like to keep playing with a free, public, lite website edition that anyone can run as a low cost implementation. I'm also playing around with managing the data using Google Spreadsheet, which syncs with the YAML in the Github repository.

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.

Improve Schema & API Definition

We have just released the alpha version for v1.1 of the Human Services Data API (HSDA) Sepcification. You can read all about this release on the Open Referral blog, but the primary objective of the release is about ensuring the API offers as much coverage of v1.1 of the HSDS schema as we can. These are some of the conversations we are having around future versions of the specification, which you can participate in via Github.

Schema Filtering

We are discussing how the user should be able to dictate how much, or how little of the schema they wish to receive with each request to the API. There are several approaches on the table, but would like to implement a solution in v1.2 or at least v1.3.

HTTP Status & Error Codes

One of the next big projects is to help figure out what guidance we will be providing with the HSDA specification in regards to which HTTP status codes should be returned, as well as developing a set of definitions for standardized error codes.

Hypermedia

One important discussion on the table is regarding the usage of hypermedia in future editions. This could be done side by side with a simpler implementation, but would bring lots of benefits to the table when it comes to pagination, relationships between elements, and alleviate some of the versioning concerns.

Response Structure

IN parrallel to the hypermedia discussion we are considering how the body should be structured, allowing for more structure to the response, even standardizing with a common media type like HAL or JSON API.

Taxonomy

Another aspect of the specification we have put on the road map is regarding the taxonomy in use for any single implementation. Ideally the platform is taxonomy agnostic, and allows for a variety of implementations supported.

Metadata

We will be working on a metadata, and operational level of APIs, and specification for any single human services implementation. This would handle change log, transactional, logging, auditing, and other aspects of operating an instance. There is much to be discussed regarding where things are going with this area.

The Github repository is the main place we are handling the final discussion as they are applied to the specification. The conversation also occurs on Google Groups, and the Slack channel, but the final thread should always be available here.

Evolve Towards Interoperability

Some interesting new additions to the Open Referral road map involves planning for the future of interoperability that will be possible when there are many disparate instances available that support the HSDS/A specification. We are discussing some key areas that will help human service providers better collaborate, crowdsource, and partner in a way that protects everyone interests. These are a handful of the core conversations going on.

Approval & Feedback

How will be allowing for an approval and feedback system for changes made to any record within an implementation, allowing for anyone to add and update information, but ensuring there is proper oversight and approval to ensure a certain quality of service.

Unique IDs

We would like to eventually accomodate a universal unique ID system that can be used across implementations, and provide some sort of provenance and history of the record. We are doing more research about best practices, as well as talking with all vendors in involved with the specification.

Webhooks

We are beginning discussions around what a webhooks system should look like for any single HSDA implementation. Opening up the external push and event aspects of operation, making things more event oriented, and a two-way street.

Messaging

This is a suggested thread to tackle the topic of messaging, and how it can be applied within a single implementation as well as across multiple human services API implementations.

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.