So far the UK and international (US-based) approaches to an Application Programming Interface (API) standard have been different. The international Human Service Data API Suite (HSDA) defines web methods that cover a broad range of options to query and update data. The UK approach is more prescriptive. It defines specific filter parameters for the /services method such that a basic generic service finder could work with any compliant API endpoint.
In discussions between UK and US teams, we’ve proposed a “minimum viable API” approach starting with just a few key web methods to ensure a compliant API endpoint would:
- work with any generic service finder
- pass tests in our dashboard and validator
- provide a full feed of data such that it could be loaded by bespoke means into an external database
I’d propose these GET web methods (a small number from the full UK set) for the minimum viable API:
-
/services - returning a paginated list of services including filter parameters for:
- page and per_page
- text
- postcode and proximity (but excluding “coverage” for now)
- taxonomy_id and vocabulary
- day, start_time and end_time
- minimum_age and maximum_age
- /services/{id} - returning full details of a given service
- /vocabularies - returning all vocabularies (taxonomies) used
- /taxonomies - returning all terms for a given vocabulary
Please say here if you think such an approach would be useful and if you think the above web methods should make up the initial minimum viable API standard.