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.
This is a working HSDA portal showing what is possible with an API that speaks the Human Services Data Specification (HSDS). Everything you should be available here on this HSDA portal. If you are looking for more information about his project, make sure you visit my Human Services Data API (HSDA) overview page.
Getting Started
There are eight separate microservices contained as part of this Human Services Data API (HSDA) work. NONE of these are officially part of the specification currently. HSDA is the core service, focusing on the management of organizations, locations, services, contacts, and their sub-resources (ie. addresses, phones, etc.). The other seven microservices are meant to be standalone services that augment the core HSDA service.
Here is a quick list of the eight services, which there are separate documentation available below:
HSDA Full - The core service for managing organizations, locations, services, contacts, and other sub-resouces in single API calls.
HSDA - The core service for managing organizations, locations, services, contacts, and other sub-resouces.
HSDA Search - A spin-off search service from the core service, focusing exclusively on searching across HSDA resources.
HSDA Bulk - An indpendent service for managing bulk submissions of data that can be then executed as job(s) on schedule.
HSDA Meta - An independent service for recording all transactions executed via any HSDA implementation, providing comprehensive logging.
HSDA Taxonomy - A spin-off service from the core specification to evolve taxonomy across core resources in multiple formats.
HSDA Management - The simple API management layer for HSDA, leveraging Github authentication to be able to make calls to HSDA APIs.
HSDA Orchestration - An independent service for handling the orchestration of activities across HSDA resources, based on events or schedule.
HSDA Utility - A set of utility APIs for manaing HSDA services, including validation, security, and other operational level needs for implementations.
To get started I recommend beginning with authentication which will get you an API key allowing you to make calls across all services, not just the public GET resources. Then spend time with the interactive documentation for each service to better understand how they work independently, but also in concert with each other. It is meant to provide a buffet of HSDA services that work together, operate independently, and can be moved forward as separate projects.
Once these projects are stabilized they will be submitted for consideration by the Open Referral community. Currently, they are simly an API Evangelist / Adopta.Agency project, working to move forwad the conversation as quickly, and efficiently as possible, using modern API patterns gathered from across the API sector.
Authentication
This implementation of HSDA leverages Github as the authentication layer for the API. Most of the GET API paths are open to the public, but any POST, PUT, DELETE, and management level APIs require an appid and appkey to accompay each request as headers.
Click on the Github logo to authentice using your Github account. The OAuth flow will take you back to this portal, adding you to the HSDA Management layer, showing you what your access keys will be. Each API call will have to contain:
x-appid - Your Github user.
x-appkey - Your Github token.
The HSDA Management service will validate your appid and appkey as being a valid Github account and token, then give access to make calls to all API paths, across all services. Invalid API requests will receive a 403 status code for any API requests.
Any valid Github user and token will work with the API, you do not need to login via the portal every time you are looking to get access for any future applications.
Human Services Data API (HSDA) Full (v1.2 DRAFT)
This is the interactive documentation for the core set of Human Services Data API (HSDA) resources. If you are looking to get a full responses for all core resources, as well as their sub-resources in a single API call, these are the paths for you. These four endpoints will return full responses for each resource in a single response.
This set of paths are intended to be about working with core resouces (ie. organizations, locations, contacts and services), there are other spearate HSDA services that give you access to a variety of systems that support, augment, and work with the core set of Human Services Data API (HSDA) services.
Human Services Data API (HSDA) (v1.2 DRAFT)
This is the interactive documentation for the core set of Human Services Data API (HSDA) resources. It provides you with everything you need to access 100% of the surface area of the Human Services Specification API (HSDS) using the web. Data is available in a CSV, JSON, or XML format. This set of paths gives you more granular level of control over resources for developing single page application (SPA), mobile, voice, and other common applications.
This set of paths are intended to be about working with core resouces (ie. organizations, locations, contacts and services), there are other spearate HSDA services that give you access to a variety of systems that support, augment, and work with the core set of Human Services Data API (HSDA) services.
Human Services Data API (HSDA) Search (v1.2 DRAFT)
This is a separate HSDA service for searching across all the core human sevices resources, pulling data with refined search criteria, separating search concerns from just working with individual human service resources.
This service was split off the core HSDA specification with the evolution of v1.2, making it it's own project, and sepaate specification from the core set of resources for working with HSDA information within any implementation.
Human Services Data API (HSDA) Taxonomy (v1.2)
This is a separate HSDA service for working with taxonomy across all the core human sevices resources, support any categorization or taxonomy, and allowing for filtering of services by taxonomy.
This service was split off the core HSDA specification with the evolution of v1.2, making it it's own project, and sepaate specification from the core set of resources for working with HSDA information within any implementation.
Human Services Data API (HSDA) Bulk (v1.2 DRAFT)
This is a HSDA sevice specificaly intended to allow the bulk submission of all the core resouces. You can submit multiple organizations, locations, services, and contacts as a single JSON. Each POST to any of the paths will not be processed immediately, but a job will be created allowing it to be run on schedule, or based upon specific events.
This is separated from the core set of resources allowing it to be run as separate set of services on a separate server allowing bulk loading of data to not impact core web, mobile, and other types of applications depending on the primary HSDA set of services.
Human Services Data API (HSDA) Meta (v1.2 DRAFT)
This is a HSDA sevice specificaly intended to manage the meta data around human services data API operations. Essentially this is a logging system, providing access to data about what API calls are made, managing individual resources, as well as any other service in use association with HSDA operations.
Currently, the primary target of this system is to allow each transaction that occurs via any HSDA implementation, and provide a way to view, and work with this transactional data. We will be adding any other logging and meta related data in each implementation.
Human Services Data API (HSDA) Management (v1.2 DRAFT)
This is a HSDA sevice specificaly intended to assist in managing HSDA access, allowing users to get at resources made available any HSDA implementation. Providing the ability to manage users, and the HSDA services they have access to.
This is the API management layer for the HSDA implementation, providing a simple solution that API providers can manage this aspect of operation. Behind the scenes this could be executed with off the shelf API management solutions. The purpose of this is to provide a common API for use across all HSDA implementations.
Human Services Data API (HSDA) Orchestration (v1.2 DRAFT)
This is a HSDA sevice specifically intended to manage orchestration around HSDA operations, enabling the system to become a two-way street, pushing data outside individual implementations. The system uses webhooks, and events to understand changes made to the HSDA system, and the data stored within.
This system works in conjunction with the HSDA Meta, and requires access to the logging of all transactions to respond to any overall, or individual event. This makes any HSDA implementation work with one or many other HSDA implementations.
Human Services Data API (HSDA) Utility (v1.2 DRAFT)
This is a HSDA sevice specifically intended to house all utility based APIs, providing a way to develop APIs that assist in the operation of HSDA implementations. These will always be more utilitiy type APIs that don't fit into any other category of HSDA service.
We will be adding APIs into this service from time to time, but only if they do not fit into their own category of HSDA service. It is the general bucket for HSDA APIs that are useful, but don't have another home.
Support
There are three ways that you can get support when using the Drone API--consider one of the following channels when you have a question, comment, or some feedback regarding the API and integration.
It is recommended that you start with submitting a Github issue, then maybe tweet at us. If your questions or comments require some privacy you should use email. Make sure you look through the existing issues before submitting a new one.
API Evangelist Partners
Contact Information.
Please contact me with any specific questions through any of these channels.