Playing With One Possible OpenAPI Spec For The Human Services Data Specification (HSDS)

Apr 9, 2016

As I was preparing for my talk with Dan from Open Referral, I published some of my thoughts on the organization, and the Human Services Data Specification (HSDS). One of the things I did as part of that work was generating of a first draft of an OpenAPI Spec for the Open Referral API. To create that draft, I used the existing Ohana API as the base, exposing the same endpoints as they did in the Code For America project. 

Over the last couple days, I spent some more time getting to know the data model set forth by HSDS, and got to work evolving my draft OpenAPI Spec to be closer in alignment with the data schema. To do this I took the JSON Schema for HSDS that was available on the Github, and generated used it as a framework to add any missing elements to the API definition, resulting in almost 70 API paths, in support of almost 20 separate entities dictated in the HSDS.

Open Referral API

OpenAPI Spec

Categories Get all categories /categories GET Contacts Get Contacts /contacts GET Create New Contact /contacts POST Get Contact /contacts/:contact_id GET Update Contact /contacts/:contact_id PUT Delete Contact /contacts/:contact_id DELETE Contact - Phones Get Phones /contacts/:contact_id/phones GET Add Phone /contacts/:contact_id/phones POST Get Phone /contacts/:contact_id/phones/:phone_id GET Update Phone /contacts/:contact_id/phones/:phone_id PUT Delete Phone /contacts/:contact_id/phones/:phone_id DELETE Locations Get Locations /locations GET Add Location /locations POST Get Location /locations/:location_id GET Update Location /locations/:location_id UPDATE Delete Location /locations/:location_id DELETE Location - Holiday Schedule Get Holiday Schedule /locations/:location_id/holiday_schedule/ GET Add Holiday Schedule /locations/:location_id/holiday_schedule/ POST Get Holiday Schedule /locations/:location_id/holiday_schedule/:holiday_schedule_id/ GET Update Holiday Schedule /locations/:location_id/holiday_schedule/:holiday_schedule_id/ PUT Delete Holiday Schedule /locations/:location_id/holiday_schedule/:holiday_schedule_id/ DELETE Location - Language Get Languages /locations/:location_id/languages/ GET Add Languages /locations/:location_id/languages/ POST Get Languages /locations/:location_id/languages/:language_id/ GET Update Languages /locations/:location_id/languages/:language_id/ PUT Delete Languages /locations/:location_id/languages/:language_id/ DELETE Location - Postal Address Get Postal Address /locations/:location_id/postal_address GET Add New Postal Adress /locations/:location_id/postal_address POST Get Postal Address /locations/:location_id/postal_address/:postal_address_id GET Update Postal Address /locations/:location_id/postal_address/:postal_address_id PUT Delete Postal Address /locations/:location_id/postal_address/:postal_address_id DELETE Location - Physical Address Get Physical Address /locations/:location_id/physical_address GET Add New Physical Adress /locations/:location_id/physical_address POST Get Physical Address /locations/:location_id/physical_address/:postal_address_id GET Update Physical Address /locations/:location_id/physical_address/:postal_address_id PUT Delete Physical Address /locations/:location_id/physical_address/:postal_address_id DELETE Location - Phones Get Phones /locations/:location_id/phones GET Add Phone /locations/:location_id/phones POST Get Phone /locations/:location_id/phones/:phone_id GET Update Phone /locations/:location_id/phones/:phone_id PUT Delete Phone /locations/:location_id/phones/:phone_id DELETE Location - Regular Schedule Get Regular Schedule /locations/:location_id/regular_schedule GET Add Regular Schedule /locations/:location_id/regular_schedule POST Get Regular Schedule /locations/:location_id/regular_schedule/:regular_schedule_id/ GET Update Regular Schedule /locations/:location_id/regular_schedule/:regular_schedule_id/ PUT Delete Regular Schedule /locations/:location_id/regular_schedule/:regular_schedule_id/ DELETE Location - Services Get Service /locations/:location_id/services/ GET Add Service /locations/:location_id/services/ POST Get Service /locations/:location_id/services/:service_id/ GET Update Service /locations/:location_id/services/:service_id/ PUT Delete Service /locations/:location_id/services/:service_id/ DELETE Location - Accessibility For Disabilities Get Accessibility For Disabilities /locations/:location_id/accessibility_for_disabilities/ GET Add Accessibility For Disabilities /locations/:location_id/accessibility_for_disabilities/ POST Get Accessibility For Disabilities /locations/:location_id/accessibility_for_disabilities/:accessibility_for_disabilities_id/ GET Update Accessibility For Disabilities /locations/:location_id/accessibility_for_disabilities/:accessibility_for_disabilities_id/ PUT Delete Accessibility For Disabilities /locations/:location_id/accessibility_for_disabilities/:accessibility_for_disabilities_id/ DELETE Metadata Get Metadata /metadata GET Add New Metadata /metadata POST Get Service /metadata/:metadata_id GET Delete Metadata /metadata/:metadata_id DELETE Organizations Get Locations /organizations GET Create a new organization /organizations POST Get Organization /organizations/:organization_id GET Update Existing Organization /organizations/:organization_id PUT Delete Organization /organizations/:organization_id DELETE Organization - Contacts Get Contacts /organizations/:organization_id/contacts GET Add Contact /organizations/:organization_id/contacts POST Get Contact /organizations/:organization_id/contacts/:contact_id/ GET Update Contact /organizations/:organization_id/contacts/:contact_id/ PUT Delete Contact /organizations/:organization_id/contacts/:contact_id/ DELETE Organization - Funding Get Funding /organizations/:organization_id/funding/ GET Add Funding /organizations/:organization_id/funding/ POST Get Funding /organizations/:organization_id/funding/:funding_id/ GET Update Funding /organizations/:organization_id/funding/:funding_id/ PUT Delete Funding /organizations/:organization_id/funding/:funding_id/ DELETE Organization - Locations Get Location /organizations/:organization_id/locations GET Create a new location /organizations/:organization_id/locations POST Update Existing Location /organizations/:organization_id/locations/:location_id/ GET Create a new location /organizations/:organization_id/locations/:location_id/ PUT Delete Location /organizations/:organization_id/locations/:location_id/ DELETE Organization - Phones Get Phones /organizations/:organization_id/phones GET Add Phone /organizations/:organization_id/phones POST Get Phone /organizations/:organization_id/phones/:phone_id GET Update Phone /organizations/:organization_id/phones/:phone_id PUT Delete Phone /organizations/:organization_id/phones/:phone_id DELETE Organization - Programs Get Programs /organizations/:organization_id/programs GET Add Program /organizations/:organization_id/programs POST Get Program /organizations/:organization_id/programs/:program_id/ GET Update Program /organizations/:organization_id/programs/:program_id/ PUT Delete Program /organizations/:organization_id/programs/:program_id/ DELETE Organization - Program Services Get Service /organizations/:organization_id/programs/:program_id/services/ GET Add Service /organizations/:organization_id/programs/:program_id/services/ POST Get Service /organizations/:organization_id/programs/:program_id/services/:service_id GET Update Service /organizations/:organization_id/programs/:program_id/services/:service_id PUT Delete Service /organizations/:organization_id/programs/:program_id/services/:service_id DELETE Organization - Services Get Services /organizations/:organization_id/services GET Add Service /organizations/:organization_id/services POST Get Service /organizations/:organization_id/services/:service_id/ GET Update Service /organizations/:organization_id/services/:service_id/ PUT Delete Service /organizations/:organization_id/services/:service_id/ DELETE Search Get locations that match certain criteria. /search GET Service - Categories Update a service’s categories /services/:service_id/categories PUT Service - Contacts Get Contacts /services/:service_id/contacts GET Add Contact /services/:service_id/contacts POST Get Contact /services/:service_id/contacts/:contact_id/ GET Update Contact /services/:service_id/contacts/:contact_id/ PUT Delete Contact /services/:service_id/contacts/:contact_id/ DELETE Service - Eligibility Get Eligibility /services/:service_id/eligibility/ GET Add Eligibility /services/:service_id/eligibility/ POST Get Eligibility /services/:service_id/eligibility/:eligibility_id/ GET Update Eligibility /services/:service_id/eligibility/:eligibility_id/ PUT Eligibility Contact /services/:service_id/eligibility/:eligibility_id/ DELETE Service - Fees Get Fees /services/:service_id/fees/ GET Add Fees /services/:service_id/fees/ POST Get Fees /services/:service_id/fees/:feed_id/ GET Update Fees /services/:service_id/fees/:feed_id/ PUT Eligibility Fees /services/:service_id/fees/:feed_id/ DELETE Service - Funding Get Funding /services/:service_id/funding/ GET Add Funding /services/:service_id/funding/ POST Get Funding /services/:service_id/funding/:funding_id/ GET Update Funding /services/:service_id/funding/:funding_id/ PUT Delete Funding /services/:service_id/funding/:funding_id/ DELETE Service - Holiday Schedule Get Holiday Schedule /services/:service_id/holiday_schedule/ GET Add Holiday Schedule /services/:service_id/holiday_schedule/ POST Get Holiday Schedule /services/:service_id/holiday_schedule/:holiday_schedule_id/ GET Update Holiday Schedule /services/:service_id/holiday_schedule/:holiday_schedule_id/ PUT Delete Holiday Schedule /services/:service_id/holiday_schedule/:holiday_schedule_id/ DELETE Service - Interpretation Services Get Interpretation Services /services/:service_id/intepretation_services/ GET Add Interpretation Services /services/:service_id/intepretation_services/ POST Get Interpretation Services /services/:service_id/intepretation_services/:intepretation_services_id/ GET Update Interpretation Services /services/:service_id/intepretation_services/:intepretation_services_id/ PUT Delete Interpretation Services /services/:service_id/intepretation_services/:intepretation_services_id/ DELETE Service - Languages Get Languages /services/:service_id/languages/ GET Add Languages /services/:service_id/languages/ POST Get Languages /services/:service_id/languages/:language_id/ GET Update Languages /services/:service_id/languages/:language_id/ PUT Delete Languages /services/:service_id/languages/:language_id/ DELETE Service - Payment Accepted Get Payment Accepted /services/:service_id/payment_accepted/ GET Add Payment Accepted /services/:service_id/payment_accepted/ POST Get Payment Accepted /services/:service_id/payment_accepted/:payment_accepted_id/ GET Update Payment Accepted /services/:service_id/payment_accepted/:payment_accepted_id/ PUT Delete Payment Accepted /services/:service_id/payment_accepted/:payment_accepted_id/ DELETE Service - Phones Get Phones /services/:service_id/phones GET Add Phone /services/:service_id/phones POST Get Phone /services/:service_id/phones/:phone_id GET Update Phone /services/:service_id/phones/:phone_id PUT Delete Phone /services/:service_id/phones/:phone_id DELETE Service - Regular Schedule Get Regular Schedule /services/:service_id/regular_schedule GET Add Regular Schedule /services/:service_id/regular_schedule POST Get Regular Schedule /services/:service_id/regular_schedule/:required_document_id/ GET Update Regular Schedule /services/:service_id/regular_schedule/:required_document_id/ PUT Delete Regular Schedule /services/:service_id/regular_schedule/:required_document_id/ DELETE Service - Required Document Get Required Document /services/:service_id/required_document/ GET Add Required Document /services/:service_id/required_document/ POST Get Required Document /services/:service_id/required_document/:required_document_id/ GET Update Required Document /services/:service_id/required_document/:required_document_id/ PUT Delete Required Document /services/:service_id/required_document/:required_document_id/ DELETE Service - Areas Get Service Area /services/:service_id/service_area/ GET Add Service Area /services/:service_id/service_area/ POST Get Service Area /services/:service_id/service_area/:service_area_id GET Update Service Area /services/:service_id/service_area/:service_area_id PUT Delete Service Area /services/:service_id/service_area/:service_area_id DELETE   Entities JSON Schema accessibility_for_disabilities id location_id accessibility contact id organization_id service_id name title department email eligibility id service_id eligibility fee id service_id fee funding id organization_id service_id source holiday_schedule id service_id location_id closed opens_at closes_at start_date end_date intepretation_services id service_id language language id service_id location_id language location id organization_id name alternate_name transportation latitude longitude metadata id resource_id last_action_date last_action_type field_name previous_value replacement_value updated_by organization id name alternate_name description email url tax_status tax_id year_incorporated legal_status payment_accepted id service_id payment phone id location_id service_id organization_id contact_id number extension type department physical_address id location_id attention address_1 address_2 address_3 address_4 city state_province postal_code country postal_address id location_id attention address_1 address_2 address_3 address_4 city state_province postal_code country program id organization_id name alternate_name regular_schedule id service_id location_id weekday opens_at closes_at required_document id service_id document service id organization_id program_id location_id name alternate_name url email status application_process wait_time service_area id service_id service_area

This is a very formulaic, generated, representation of what the Open Referral API could look like. While I have lots of ideas on how to improve on the design, I want to be cautious to not project too much of my own views on the API design--something the community should do together. I can tell a lot of work went into the current specification, and the same amount of energy should go into evolving the API design.

I accomplished what I wanted. Learn more about HSDS, get more familiar with the entities at play, while also producing a fairly robust representation of what an API could look like for Open Referral. It has way more details than the average implementation will need, but I wanted to cover all the bases, providing full control over every entity, and relationship represented in HSDS. Most importantly I was able to get more intimate with the specification, while also producing an OpenAPI Spec that will playing a central role throughout this project.

Next I'm going to play with some minimum viable representations, and other ways to tell stories and talk about the HSDS. I'd like to eventually have a whole toolbox of YAML / JSON driven UI elements, like the one I pasted in this post, allowing me to describe all the moving parts of the Open Referral work. More posts to come, as I work through my thoughts, and play possible designs for the Human Services Data Specification (HSDS).

---

← Previous

Next →