api-specification

⚠️ This repo has been archived, and is no longer maintained ⚠️

HSDS 3.0 introduces an API specification which replaces this one, and is versioned as part of the HSDS standard. Please check for and raise issues on the HSDS Specification Issue tracker.

Old issues on this repository have been closed if they were addressed as part of HSDS 3.0. Issues that remain open have been documented and will be linked to from appropriate places e.g. new issues in the HSDS Specification repository, or in community forums. If you wish to explicitly restart an existing discussion from an Issue in this repo, please open a new issue in the HSDS Specification repository and link back to the issue you want to continue.

Open Referral Human Services Data API (HSDA)

This is the repository for managing the Open Referral Human Services Data API (HSDA), providing a common interface for accessing organizations, locations, services, and contacts for 211 human services information.

Key Links

• Open Referral Website
• HSDS Documentation
• HSDA Documentation

HSDA v2.0 OpenAPIs

HSDA uses the OpenAPI specification to describe the surface area of the API, providing a machine readable definition for all of HSDA.

• HSDA (OpenAPI on GitHub) (OpenAPI in Workspace) (Collection in Workspace)
• HSDA Search (OpenAPI on GitHub) (OpenAPI in Workspace) (Collection Docs in Workspace)
• HSDA Meta (OpenAPI on GitHub) (OpenAPI in Workspace) (Collection Docs in Workspace)
• HSDA Taxonomy (OpenAPI on GitHub) (OpenAPI in Workspace) (Collection Docs in Workspace)

Drafts for v2.0 are currently being finalized and open for comments–here is how you can provide feedback:

• GitHub Issues - You can submit a Github issue with your feedback or OpenAPI reference.
• Postman API Comments - You can comment on each of the OpenAPI as well as each individual part of the API.

Using OpenAPI helps ground the conversation around each of the APIs being evolved here. It significantly helps to submit the OpenAPI snippet with suggested changes, or highlight and common on the portion of the OpenAPI you wish to provide feedback on. Feel free to all submit pull requests on OpenAPIs via Github, or collections via Postman.

You can follow along with work in the public workspace for the HSDA APIs as we work to finalize and standardize the OpenAPIs for HSDA. Your feedback is appreciated.

HSDA v2.0 Major Changes

Here are the highlights of the HSDA v2.0 update, with the focus being on HSDS upgrade, but using the opportunity to clean up some other areas of the HSDA specification.

• HSDS v2.0 Update - All of the schema were brought up to date with version 2.0 of HSDS.
• Standardized Querying - We standardized the search across contacts, locations, organizations, and services, as well as for search–the query standard is outline here.
• Header Pagination - A set of headers were added to each of the root level resources, showing you the details of pagination for each query.
• Status Codes - Status codes were standardized across all responses, providing a consistent set of HTTP status codes for all API paths.
• RFC 7807 for Errors - We standardized the error responses for 4xx and 5xx errors, providing a common approach to reporting problems using RFC 7807 - Problem Details for HTTP APIs.

The new standardized query structure dealt with a number of the issues that were submitted, while allowing for basic keyword search, as well as a much more complex approach that allows querying by any field, while also having full control over what gets returned.

This site is open source. Improve this page.