Making All Sub-Resources Available Within The Core Set Of Human Service APIs

I had recently taken the Human Services Data Specification (HSDS) and exposed it as a set of API paths that provide access to about 95% of the schema, which we are calling the Human Services Data API (HSDA). When you make a call to the /organizations/ path, you receive an array collection of organizations that each match the HSDA organization schema. The same applies when you make a call to the /locations, /contacts, and /services, opening up access to the entire schema–minus three objects I pushed off until future releases.

After the core set of API paths /organization, /service, /location, /contact, there are a set of sub-resources available across those as it makes sense–including /phone, /programs, /physical_address, /postal_address, /regular_schedule, /holiday_schedule, /funding, /eligibility, /service_area, /required_document, /payment_accepted, /language, /accessiblity_for_disabilities, and /service_at_location_id. I took the HSDA schema, and published API paths for each sub-resource so that it exactly returned, and accepted HSDA compliant schema–making all aspects of the schema accessible via an API, with POST and PUT requests accepting compliant schema, and GET returning compliant schema.

One of the “stoppers” we received from several folks in the HSDS community during the feedback cycle going from version 1.0 of the API to version 1.1, was that the design was overly complex, and that it would serve any of the human services use cases on the table currently, unless you could get at all the sub resources directly with each core API path, eliminating the need for making additional call(s) to each sub-resource. You could get at everything about an /organization, /service, /location, and /contact in a single API URL.

Currently the core four API paths accept and return the following schema:

Organization

Field Name Type (Format) Description Required? Unique?
id string (uuid) Each organization must have a unique identifier. True True
name string The official or public name of the organization. True False
alternate_name string Alternative or commonly used name for the organization. False False
description string A brief summary about the organization. It can contain markup such as HTML or Markdown. True False
email string (email) The contact e-mail address for the organization. False False
url string (url) The URL (website address) of the organization. False False
tax_status string Government assigned tax designation for for tax-exempt organizations. False False
tax_id string A government issued identifier used for the purpose of tax administration. False False
year_incorporated date (%Y) The year in which the organization was legally formed. False False
legal_status string The legal status defines the conditions that an organization is operating under; e.g. non-profit, private corporation or a government organization. False False

Service

Field Name Type (Format) Description Required? Unique?
id string Each service must have a unique identifier. True True
organization_id string The identifier of the organization that provides this service. True False
program_id string The identifier of the program this service is delivered under. False False
name string The official or public name of the service. True False
alternate_name string Alternative or commonly used name for a service. False False
description string A description of the service. False False
url string (url) URL of the service False False
email string (email) Email address for the service False False
status string The current status of the service. True False
interpretation_services string A description of any interpretation services available for accessing this service. False False
application_process string The steps needed to access the service. False False
wait_time string Time a client may expect to wait before receiving a service. False False
fees string Details of any charges for service users to access this service. False False
accreditations string Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization. False False
licenses string An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here. False False
taxonomy_ids string (Deprecated) A comma separated list of identifiers from the taxonomy table. This field is deprecated in favour of using the service_taxonomy table. False False

Location

Field Name Type (Format) Description Required? Unique?
id string Each location must have a unique identifier True False
organization_id string Each location entry should be linked to a single organization. This is the organization that is responsible for maintaining information about this location. The identifier of the organization should be given here. Details of the services the organisation delivers at this location should be provided in the services_at_location table. False False
name string The name of the location False False
alternate_name string An alternative name for the location False False
description string A description of this location. False False
transportation string A description of the access to public or private transportation to and from the location. False False
latitude number Y coordinate of location expressed in decimal degrees in WGS84 datum. False False
longitude number X coordinate of location expressed in decimal degrees in WGS84 datum. False False

Contact

Field Name Type (Format) Description Required? Unique?
id string Each contact must have a unique identifier True False
organization_id string The identifier of the organization for which this is a contact False False
service_id string The identifier of the service for which this is a contact False False
service_at_location_id string The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location. False False
name string The name of the person False False
title string The job title of the person False False
department string The department that the person is part of False False
email string (email) The email address of the person False False

To ensure that all sub-resource area available as part of each of the requests and responses for all core API paths, we are going to have to evolve the HSDS schema to be:

Organization

Field Name Type (Format) Description Required? Unique?
id string (uuid) Each organization must have a unique identifier. True True
name string The official or public name of the organization. True False
alternate_name string Alternative or commonly used name for the organization. False False
description string A brief summary about the organization. It can contain markup such as HTML or Markdown. True False
email string (email) The contact e-mail address for the organization. False False
url string (url) The URL (website address) of the organization. False False
tax_status string Government assigned tax designation for for tax-exempt organizations. False False
tax_id string A government issued identifier used for the purpose of tax administration. False False
year_incorporated date (%Y) The year in which the organization was legally formed. False False
legal_status string The legal status defines the conditions that an organization is operating under; e.g. non-profit, private corporation or a government organization. False False
services array Returns a collection of services for each organization False False
locations array Returns a collection of locations for each organization False False
contacts array Returns a collection of contacts for each organization False False
phones array Returns a collection of phones for each organization False False
programs array Returns a collection of programs for each organization False False
fundings array Returns a collection of fundings for each organization False False

Service

Field Name Type (Format) Description Required? Unique?
id string Each service must have a unique identifier. True True
organization_id string The identifier of the organization that provides this service. True False
program_id string The identifier of the program this service is delivered under. False False
name string The official or public name of the service. True False
alternate_name string Alternative or commonly used name for a service. False False
description string A description of the service. False False
url string (url) URL of the service False False
email string (email) Email address for the service False False
status string The current status of the service. True False
interpretation_services string A description of any interpretation services available for accessing this service. False False
application_process string The steps needed to access the service. False False
wait_time string Time a client may expect to wait before receiving a service. False False
fees string Details of any charges for service users to access this service. False False
accreditations string Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization. False False
licenses string An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here. False False
taxonomy_ids string (Deprecated) A comma separated list of identifiers from the taxonomy table. This field is deprecated in favour of using the service_taxonomy table. False False
contacts array Returns a collection of contacts for each service. False False
phones array Returns a collection of phones for each service. False False
regular_schedules array Returns a collection of regular schedules for each service. False False
holiday_schedules array Returns a collection of holiday schedules for each service. False False
fundings array Returns a collection of fundings for each service. False False
eligibilities array Returns a collection of eligibilities for each service. False False
service_areas array Returns a collection of service areas for each service. False False
required_documents array Returns a collection of required documents for each service. False False
payments_accepted array Returns a collection of payments accepted for each service. False False
languages array Returns a collection of languages for each service. False False

Location

Field Name Type (Format) Description Required? Unique?
id string Each location must have a unique identifier True False
organization_id string Each location entry should be linked to a single organization. This is the organization that is responsible for maintaining information about this location. The identifier of the organization should be given here. Details of the services the organisation delivers at this location should be provided in the services_at_location table. False False
name string The name of the location False False
alternate_name string An alternative name for the location False False
description string A description of this location. False False
transportation string A description of the access to public or private transportation to and from the location. False False
latitude number Y coordinate of location expressed in decimal degrees in WGS84 datum. False False
longitude number X coordinate of location expressed in decimal degrees in WGS84 datum. False False
phones array Returns a collection of phones for each location. False False
physical_addresses array Returns a collection of physical addresses for each location. False False
postal_addresses array Returns a collection of postal addresses for each location. False False
regular_schedules array Returns a collection of regular schedules for each location. False False
holiday_schedules array Returns a collection of holiday schedules for each location. False False
languages array Returns a collection of languages for each location. False False
accessiblity_for_disabilities array Returns a collection of accessiblity_for_disabilities for each location. False False

Contact

Field Name Type (Format) Description Required? Unique?
id string Each contact must have a unique identifier True False
organization_id string The identifier of the organization for which this is a contact False False
service_id string The identifier of the service for which this is a contact False False
service_at_location_id string The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location. False False
name string The name of the person False False
title string The job title of the person False False
department string The department that the person is part of False False
email string (email) The email address of the person False False
phones array Returns a collection of phones for each contact False False

Once we add all relevant sub-resources added as arrays to the HSDS schema, we can allow API consumers to POST and PUT, or GET using as little, or as much of the schema using the path, header, or parameter. Allowing for reading and writing HSDS at the granular level, or everything at once using a single path.

Next we need to consider this updated schema as part of the 1.2 release of HSDS. If we update HSDA to allow for filtering the schema across /organization, /service, /location, and /contact, and return each sub-resource as part of the API request or response, it will be out of sync with HSDS. Ideally, both HSDS, and HSDA move forward in sync with each version. I’m curious why this expanded schema became such an issue once we got to the API phase–it seems like it should have been part of v1.1 of HSDS, making the schema drive the API instead of the other way around.

I’m guessing that these concerns about schema don’t come into focus until we start talking about access to the schema, and data. Making the separation and relationships between HSDS and HSDA all the more important, providing a framework to move the schema forward in a way that is rooted in how it will actually be accessed. Which is why we do APIs…