From my perspective, I see these cases for having standard API methods with consistent responses from different Open Referral API (HSDA) endpoints:
Allow social prescribing tools to read details of services suitable for prescribing to people with different needs. The UK NHS procurement framework for social prescribing requires tools to be able to read from Open Referral UK endpoints
Allow service finder tools to be developed to work with any API feed. This is important because it stimulates the market for independent development of tools that would not be viable if they needed different connectors for every published dataset’s API. It also reinforces the separation of backend databases from frontend tools using the data and so helps reduce vendor tie-in
Allow aggregation (combining) of services data from multiple publishers for a geographical area where directories are compiled by many different public, private and voluntary organisations.
Allow use of generic tools in multiple circumstances, such as the dashboard, the API query tool, the exporter and the validator developed in the UK. Future such tools can be developed once and shared across all consumers. In the UK we tell people procuring a directory to ensure it passes validation via the validator.
Mike thanks for kicking this off. I agree that it would help to start specifying a set of use cases for the API protocols, and I’m trying to understand the right format for this.
(It’s a bit unlike typical use case development which is about end-users, whereas here I think the API protocol’s users are people who build programs and run functions to enable downstream tools that help end-users – so it seems like our use case documentation should have at least a degree of abstraction from that which would support typical UX development?)
I now have at least one example from the US – see the documentation of 2-1-1 Michigan’s implementation of HSDS in their API portal here, with these use cases specified to support it.
Meanwhile, Mike: can you help me understand the differences between #1, #3, and #4 in your list here? They all read to me very similarly, I wonder if we can work to disambiguate a bit here…
This entails providing social prescribers with sufficient information to be able to identify services of types that are likely to meet the needs and circumstances of an individual. When such services are identified, social prescribers need information that lets the individual make use of the service (e.g. contact details).
This means supporting federated data whereby multiple organisations publish and maintain their own services data but this data can be harvested and brought together in one place for a particular purpose. For example an online service directory for an English county might take its data from the county local authority, multiple (smaller) district authorities, health organisations and a community/voluntary directory. Once brought together in one place, the combined data must not lose meaning. This implies:
being in the same data structure or (failing that) being in structures that can be mapped to a common structure
using the same taxonomies for terms or (failing that) using taxonomies that can be mapped to a common taxonomy
avoiding duplication of records by using identifiers that are unique across all harvested sources and have fields (e.g. charity number) that help find duplicates from different sources
This means having a structure that can be read by generic tools, so for example, the /services GET method having the same response format wherever the data comes from.
If that’s not clear, ask again and I’ll try to explain more.
Thanks, and I have to apologize: it was not#3, but rather #2 that seemed to me to be possibly redundant with #1 and #4…
at this phase wouldn’t a social prescribing tool reading details of services be, essentially, a ‘service finder tool’ that should work with any API feed? Also, might we consider a “service finder tool” to be a “generic tool”? I could guess at ways to distinguish between these but curious to hear from you.