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
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
accessibility_for_disabilities
- id
- location_id
- accessibility
contact
- id
- organization_id
- service_id
- name
- title
- department
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
- 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
- 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).
