This is a working project for the Open Referral Human Services Data API Specification.
You can view the public side of this project: https://openreferral.github.io/api-specification/
Here is a summary of what we are consider currently as part of the specification, as we take in feedback from the community of provides, vendors, and other human services stake holders.
We are currently moving the API definition from v1.0 to v1.1, with a focus on ensuring the API covers 100% of the surface area for the Human Services Data Specification (HSDS).
- Here is OpenAPI for version 1.0 of the HSDA - https://openreferral.github.io/api-specification/definition/v10/
- Here is OpenAPI for version 1.1 of the HSDA - https://openreferral.github.io/api-specification/definition/
- Versioning - Guidance for versioning each API and communicating about what is supported.
- Paths - The discussion around creating paths.
- Verbs - here is the thread for further discussions around verbs.
- Actions - Preparing for the future when we have more actions to be taken.
- Parameters - The parameters discussion issue.
- Headers - The header discussions.
- Body - Discussion around usage of the request body.
- Pagination - Evolving on current approach to using page= and per_page=.
- Body Usage - How we are using the body of each request.
- Data Filtering - Discussions around how to filter data, allowing API consumers to search across the contents of any implementation.
- Schema Filtering - Considering the design of simple, standard, or full schema responses that can fe specificed using a prefer header.
- Sorting - How we are going to handle sorting.
- Operation ID - Decision around the operationID for each unique path.
- Response Structure - More conversation about how to structure responses.
- Status Codes - Discussion around the status codes to return.
- Hypermedia - Conversations around future hypermedia usage.
- GraphQL - Discussion around using GraphQL to allow for more advanced usage and querying.
- Public - All the GET paths are publicly available, with no metering on them beyond just server logs.
- Github - All the POST, PUT, and DELETE require an x-appid and x-appkey, which are a Github username and valid Github token for user who is contributor on the Github repository for the API implementation.
- Demo Portal and API - The demo portal setup for the project running PHP Slim on AWS linux instance for the API, and the developer portal running on Github Pages.
- Data Privacy Conversation - The open issue discussing privacy concerns.
I am evaluating a handful of vendors and their schema and APIs as part of moving forward the specification. Here are the vendors I'm looking at currently:
- iCarol
- Vision Link
- Health Leads
- AIRS - Comoparing their schema and API work to the HSDS/A spec.
- Taxonomy - Earlier conversations around taxonomy. I am considering the wider picture when it comes to taxonomy, and what is available via the API.
- Metadata - Putting off metadata paths until there is more discussion about how this will work with API deployment and management infrastructure.
- Scheduling and Calendaring - Suggestions around evolving the regular and holiday scheduling to think about calendaring.