Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
690 lines (689 sloc) 22.9 KB
swagger: '2.0'
info:
title: "Human Services Data Taxonomy API"
description: "This is a complimentary API to the HSDA API focusing just on taxonomy."
termsOfService: "https://openreferral.org/documentation/"
contact:
name: Open Referral
url: https://openreferral.org/
email: info@openreferral.org
license:
name: Open Data Commons Public Domain
url: https://creativecommons.org/licenses/by-sa/4.0/
version: v1.0
host: hsda.taxonomy.api.adopta.agency
basePath: /
schemes:
- http
produces:
- application/json
paths:
/taxonomy/:
get:
summary: Get Taxonomy
description: Get Taxonomy
operationId: listTaxonomy
security:
- appid: []
- appkey: []
responses:
'200':
description: Item Response
schema:
type: array
items:
$ref: "#/definitions/taxonomy"
tags:
- Taxonomy
post:
summary: Add taxonomy
description: Addtaxonomy
operationId: addTaxonomy
parameters:
- in: body
name: body
schema:
$ref: '#/definitions/taxonomy'
security:
- appid: []
- appkey: []
responses:
'200':
description: Taxonomy Response
schema:
type: array
items:
$ref: "#/definitions/taxonomy"
'403':
description: No Access Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
'500':
description: Error Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
tags:
- Taxonomy
/taxonomys/{taxonomy_id}/:
get:
summary: Get Taxonomy
description: Get Taxonomy
operationId: getTaxonomy
parameters:
- in: path
required: true
type: string
name: taxonomy_id
description: The taxonomy id.
responses:
'200':
description: Taxonomy Response
schema:
type: array
items:
$ref: "#/definitions/taxonomy"
'500':
description: Error Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
tags:
- Taxonomy
put:
summary: Update Taxonomy
description: Update Taxonomy
operationId: updateTaxonomy
parameters:
- in: path
required: true
type: string
name: taxonomy_id
description: 'The unique taxonomy id.'
- in: body
name: body
schema:
$ref: '#/definitions/taxonomy'
security:
- appid: []
- appkey: []
responses:
'200':
description: Taxonomy Response
schema:
type: array
items:
$ref: "#/definitions/taxonomy"
'403':
description: No Access Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
'500':
description: Error Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
tags:
- Taxonomy
delete:
summary: Delete Taxonomy
description: Delete Taxonomy
operationId: deleteTaxonomy
parameters:
- in: path
required: true
type: string
name: taxonomy_id
description: The taxonomy id.
tags:
- Taxonomy
security:
- appid: []
- appkey: []
responses:
'200':
description: Taxonomy Response
schema:
type: array
items:
$ref: "#/definitions/taxonomy"
'403':
description: No Access Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
'500':
description: Error Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
/services/{taxonomy_name}/:
get:
summary: Get Services
description: Get Services
operationId: listServices
parameters:
- in: path
required: true
type: string
name: taxonomy_name
description: The taxonomy name.
- in: query
type: string
name: query
description: A query to filter list by (up to provider to determine what to search)
- in: query
type: string
name: queries
description: A comma separate list of queries with specific fields.
- in: query
type: number
name: page
default: 0
description: The particular page of results.
- in: query
type: number
name: per_page
default: 25
description: Number of records return per page, up to 100.
- in: query
type: string
name: sort_by
default: name
description: Which field to sort by.
- in: query
type: string
name: order
default: asc
description: Which order to sort by (asc,desc).
responses:
'200':
description: Service Response
schema:
type: array
items:
$ref: "#/definitions/service"
'500':
description: Error Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
tags:
- Services
/services/complete/{taxonomy_name}/:
get:
summary: Get Services (Complete)
description: Get Services (Complete)
operationId: listServicesComplete
parameters:
- in: path
required: true
type: string
name: taxonomy_name
description: The taxonomy name.
- in: query
type: string
name: query
description: A query to filter list by (up to provider to determine what to search)
- in: query
type: string
name: queries
description: A comma separate list of queries with specific fields.
- in: query
type: number
name: page
default: 0
description: The particular page of results.
- in: query
type: number
name: per_page
default: 25
description: Number of records to return per page, up to 100.
- in: query
type: string
name: sort_by
default: name
description: Which field to sort by.
- in: query
type: string
name: order
default: asc
description: Which order to sort by (asc,desc).
responses:
'200':
description: Service Complete Response
schema:
type: array
items:
$ref: "#/definitions/service_complete"
'500':
description: Error Response
schema:
type: array
items:
$ref: "#/definitions/error_response"
tags:
- Services
securityDefinitions:
appid:
type: apiKey
in: header
name: x-appid
appkey:
type: apiKey
in: header
name: x-appkey
definitions:
taxonomy:
properties:
id:
description: 'Each taxonomy entry must have a unique identifier. If combining multiple taxonomies with overlapping identifiers, use a prefix to distinguish them.'
type: string
name:
description: 'The name of this taxonomy term or category.'
type: string
parent_id:
description: 'If this is a child category in a hierarchical taxonomy, give the identifier of the parent category. For top-level categories, this should be left blank.'
type: string
parent_name:
description: 'If this is a child category in a hierarchical taxonomy, give the name of the parent category. For top-level categories, this should be left blank.'
type: string
vocabulary:
description: 'If this is an established taxonomy, detail which taxonomy is in use. For example, AIRS or Open Eligibility.'
type: string
required:
- id
- name
service:
properties:
id:
description: 'Each service must have a unique identifier.'
type: string
organization_id:
description: 'The identifier of the organization that provides this service.'
type: string
program_id:
description: 'The identifier of the program this service is delivered under.'
type: string
location_id:
description: 'The identifier of the location where this service is delivered.'
type: string
name:
description: 'The official or public name of the service.'
type: string
alternate_name:
description: 'Alternative or commonly used name for a service.'
type: string
description:
description: 'A description of the service.'
type: string
url:
description: 'URL of the service.'
type: string
email:
description: 'Email address for the service.'
type: string
status:
description: 'The current status of the service.'
type: string
interpretation_services:
description: 'A description of any interpretation services available for accessing this service.'
type: string
application_process:
description: 'The steps needed to access the service.'
type: string
wait_time:
description: 'Time a client may expect to wait before receiving a service.'
type: string
fees:
description: 'Details of any charges for service users to access this service.'
type: string
accreditations:
description: 'Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.'
type: string
licenses:
description: 'An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.'
type: string
service_complete:
properties:
id:
description: 'Each service must have a unique identifier.'
type: string
organization_id:
description: 'The identifier of the organization that provides this service.'
type: string
program_id:
description: 'The identifier of the program this service is delivered under.'
type: string
location_id:
description: 'The identifier of the location where this service is delivered.'
type: string
name:
description: 'The official or public name of the service.'
type: string
alternate_name:
description: 'Alternative or commonly used name for a service.'
type: string
description:
description: 'A description of the service.'
type: string
url:
description: 'URL of the service.'
type: string
email:
description: 'Email address for the service.'
type: string
status:
description: 'The current status of the service.'
type: string
interpretation_services:
description: 'A description of any interpretation services available for accessing this service.'
type: string
application_process:
description: 'The steps needed to access the service.'
type: string
wait_time:
description: 'Time a client may expect to wait before receiving a service.'
type: string
accreditations:
description: 'Details of any accreditations. Accreditation is the formal evaluation of an organization or program against best practice standards set by an accrediting organization.'
type: string
licenses:
description: 'An organization may have a license issued by a government entity to operate legally. A list of any such licenses can be provided here.'
type: string
contacts:
type: "array"
items:
$ref: "#/definitions/contact"
eligibility:
type: "array"
items:
$ref: "#/definitions/eligibility"
fees:
type: "array"
items:
$ref: "#/definitions/fee"
funding:
type: "array"
items:
$ref: "#/definitions/funding"
regular_schedule:
type: "array"
items:
$ref: "#/definitions/regular_schedule"
holiday_schedule:
type: "array"
items:
$ref: "#/definitions/holiday_schedule"
languages:
type: "array"
items:
$ref: "#/definitions/language"
payment_accepted:
type: "array"
items:
$ref: "#/definitions/payment_accepted"
phones:
type: "array"
items:
$ref: "#/definitions/phone"
required_documents:
type: "array"
items:
$ref: "#/definitions/required_document"
service_area:
type: "array"
items:
$ref: "#/definitions/service_area"
required:
- id
- organization_id
- name
- status
contact:
properties:
id:
description: 'Each contact must have a unique identifier.'
type: string
organization_id:
description: 'The identifier of the organization for which this is a contact.'
type: string
service_id:
description: 'The identifier of the service for which this is a contact.'
type: string
service_at_location_id:
description: 'The identifier of the ‘service at location’ table entry, when this contact is specific to a service in a particular location.'
type: string
name:
description: 'The name of the person.'
type: string
title:
description: 'The job title of the person.'
type: string
department:
description: 'The department that the person is part of.'
type: string
email:
description: 'The email address of the person.'
type: string
required:
- id
eligibility:
properties:
id:
description: 'Each entry must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the service for which this entry describes the eligibility criteria.'
type: string
eligibility:
description: 'The rules or guidelines that determine who can receive the service.'
type: string
required:
- id
fee:
properties:
id:
description: 'Each entry must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the service for which this entry describes the costs of service.'
type: string
fee:
description: 'A listing of the costs of services, including free ones.'
type: string
required:
- id
funding:
properties:
id:
description: 'Each entry must have a unique identifier.'
type: string
organization_id:
description: 'The identifier of the organization for which this entry describes the source of funding.'
type: string
service_id:
description: 'The identifier of the service for which this entry describes the source of funding.'
type: string
source:
description: 'Source of funds for organization or service.'
type: string
required:
- id
holiday_schedule:
properties:
id:
description: 'Each entry must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the service for which this is the holiday schedule.'
type: string
location_id:
description: 'The identifier of the location for which this is the holiday schedule.'
type: string
service_at_location_id:
description: 'The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.'
type: string
closed:
description: 'Indicates if a service or location is closed during a public holiday.'
type: boolean
opens_at:
description: 'The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
type: string
closes_at:
description: 'The time when a service or location closes. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
type: string
start_date:
description: 'The first day that a service or location is closed during a public or private holiday.'
type: string
end_date:
description: 'The last day that a service or location is closed during a public or private holiday.'
type: string
required:
- id
- closed
- start_date
- end_date
regular_schedule:
properties:
id:
description: 'Each entry must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the service for which this is the regular schedule.'
type: string
location_id:
description: 'The identifier of the location for which this is the regular schedule.'
type: string
service_at_location_id:
description: 'The identifier of the ‘service at location’ table entry, when this schedule is specific to a service in a particular location.'
type: string
weekday:
description: 'The day of the week that this entry relates to.'
type: string
opens_at:
description: 'The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
type: string
closes_at:
description: 'The time when a service or location opens. This should use HH:MM format and should include timezone information, either adding the suffix ‘Z’ when the date is in UTC, or including an offset from UTC (e.g. 09:00-05:00 for 9am East Coast Time.'
type: string
required:
- id
- weekday
language:
properties:
id:
description: 'Each language must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the service for which the entry describes the languages in which services are delivered.'
type: string
location_id:
description: 'The identifier of the location for which the entry describes the languages in which services are delivered.'
type: string
language:
description: 'Languages, other than English, in which the service is delivered. Languages are listed as ISO639-1 codes..'
type: string
required:
- id
payment_accepted:
properties:
id:
description: 'Each entry must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the services for which the entry describes the accepted payment methods.'
type: string
payment:
description: 'The methods of payment accepted for the service.'
type: string
required:
- id
required_document:
properties:
id:
description: 'Each document must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the service for which this entry describes the required document.'
type: string
document:
description: 'The document required to apply for or receive the service. e.g. Government-issued ID, EU Passport.'
type: string
required:
- id
phone:
properties:
id:
description: 'Each entry must have a unique identifier.'
type: string
location_id:
description: 'The identifier of the location where this phone number is located.'
type: string
service_id:
description: 'The identifier of the service for which this is the phone number.'
type: string
organization_id:
description: 'The identifier of the organisation for which this is the phone number.'
type: string
contact_id:
description: 'The identifier of the contact for which this is the phone number.'
type: string
service_at_location_id:
description: 'The identifier of the ‘service at location’ table entry, when this phone number is specific to a service in a particular location.'
type: string
number:
description: 'The phone number.'
type: string
extension:
description: 'The extension of the phone number.'
type: string
type:
description: 'Whether the phone number relates to a fixed or cellular phone.'
type: string
department:
description: 'The department for which this is the phone number.'
type: string
language:
description: 'A comma separated list of ISO 639-1, or ISO 639-2 [language codes](available at http://www.loc.gov/standards/iso639-2/php/code_list.php) to represent the languages available from this phone service. The three-letter codes from ISO 639-2 provide greater accuracy when describing variants of languages, which may be relevant to particular communities.'
type: string
description:
description: 'A description providing extra information about the phone service (e.g. any special arrangements for accessing, or details of availability at particular times.'
type: string
required:
- id
- number
service_area:
properties:
id:
description: 'Each service area must have a unique identifier.'
type: string
service_id:
description: 'The identifier of the service for which this entry describes the service area.'
type: string
service_area:
description: 'The geographic area where a service is available. This is a free-text description, and so may be precise or indefinite as necessary.'
type: string
description:
description: 'A more detailed description of this service area. Used to provide any additional information that cannot be communicated using the structured area and geometry fields.'
type: string
required:
- id
error_response:
properties:
code:
description: 'Repeat the HTTP status code'
type: integer
message:
description: 'A plain language message explaining the error'
type: integer