Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Playing With One Possible OpenAPI Spec for the Human Services Data Specification (HSDS)

DZone's Guide to

Playing With One Possible OpenAPI Spec for the Human Services Data Specification (HSDS)

JSON and API Design

· Integration Zone
Free Resource

Modernize your application architectures with microservices and APIs with best practices from this free virtual summit series. Brought to you in partnership with CA Technologies.

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
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
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
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
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).

The Integration Zone is proudly sponsored by CA Technologies. Learn from expert microservices and API presentations at the Modernizing Application Architectures Virtual Summit Series.

Topics:
api ,process automation ,zapier ,json api ,small business ,api design ,github

Published at DZone with permission of Kin Lane, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

THE DZONE NEWSLETTER

Dev Resources & Solutions Straight to Your Inbox

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.

X

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}