This Is A Beta Implementation -- Feel Free To Poke Around, But Things Won't Always Works - Use Github Issues for questions.

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.

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.