***** OpenAPI Stored In /_data/api-commons/openapi.yaml *****
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/
- Validation - Produce JSON schema for HSDS and HSDS, and publish API definition, and working HSDS/a API for validating.
- Finalize - Take any feedback from Slack, Github, Google Group, and Spreadsheet and finalize the release of HSDA v1.1
- Use Cases - We need use cases for any possible scenario in which HSDS/A will be put to work.
- /everything - add an /everything to each core resource, allowing access to all sub resouces.
- /search - give search a different response that spans all objects.
- Use Cases - We need use cases for any possible scenario in which HSDS/A will be put to work.
- fields= parameter - Add a parameter for filtering which fields and sub-resources get returned as part of response.
- Error Codes - Establish a set of object definitions for returning errors as part of responses.
- Status Code - Establish a set of status codes across all paths, and associate as reponses.
- Use Cases - We need use cases for any possible scenario in which HSDS/A will be put to work.
- Domain Guidance - Thoughts about whether or not we should be offering domain guidance in the future. Not worried about for v1.1, but maybe later.
- 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 Scope / Filtering - Discussions around how to filter data, allowing API consumers to search across the contents of any implementation.
- Schema Scope / Filtering - Considering the design of simple, standard, or full schema responses that can fe specificed using a prefer header.
- Path Scope / Filtering - This won't be in the API design per se, but in the documentation (APIs.json), allowing for grouping and filtering of available paths similar to schema and data above
- Project Scope / Filtering - Adding the fourth dimension to this scope / filtering discussion, I'm proposing we dicuss how projects are defined and isolated, which can allow them to move forward at different rates, and be reflected in documentation, code, and other resources--allowing for filtering by consumers.
- 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.
- Content Negotiation - Augmenting other conversations, begin introducing content negotiation concepts to the discussion.
- 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.
- Approval & Feedback - Discussion around how we are going to allow for the approval, notificiation, and feedback system around any change to a record in the system.
- Universal Unique IDs - How will we allow for a universal uniqud ID system for all organizations, locations, and services, providing some provenance on the origin of the record.
- Messaging - Suggesting that we isolate the messaging guidance for APIs, setting a standard for how you communicate within a single implementation as well across implementations.
- Webhooks - How will we allow for a universal uniqud ID system for all organizations, locations, and services, providing some provenance on the origin of the record.
- 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.
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.
- Data Privacy Conversation - The open issue discussing privacy concerns.
- 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.
- Logging - I want to start coming up with guidance for logging, either as part of API structure, or offloaded to API management solutions.
- Scheduling and Calendaring - Suggestions around evolving the regular and holiday scheduling to think about calendaring.
- GraphQL - Discussion around using GraphQL to allow for more advanced usage and querying.