kinlane
4/24/2016 - 6:03 AM

Human Services Data Specification Open API Spec

Human Services Data Specification Open API Spec

swagger: '2.0'
info:
  title: "Open Referral API"
  description: "This is a specification describing the Open Referral API, using the Human Services Specification. This has been extracted from the Ohana API deployment, but will be standardized to refer to the universal standard that will apply to any Open Referral compliant API."
  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: http://opendatacommons.org/licenses/pddl/
  version: v1.0
host: api.example.com
basePath: "/"
schemes:
- https
produces:
- application/json
paths:
  "/locations/":
    get:
      summary: Locations
      description: Retrieve all of the locations available.
      operationId: retrieveLocations
      parameters:
        - name: Accept
          in: header
          type: string
          required: true
          default: 'application/vnd.ohanapi+json; version=1'
        - name: page
          in: query
          type: string
          required: false
        - name: per_page
          in: query
          type: string
          required: false
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
      - Locations
    post:
      summary: Locations
      description: Creates a new location in the system.
      operationId: createLocations
      parameters:
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
      - Locations
  "/locations/{location_id}/":
    get:
      summary: Location
      description: Retrieve all of the locations available in this database.
      operationId: retrieveLocation
      parameters:
        - name: Accept
          in: header
          type: string
          required: true
          default: 'application/vnd.ohanapi+json; version=1'
        - name: location_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
        - Locations
    patch:
      summary: Locations
      description: Updates an existing location in the system.
      operationId: updateLocation
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
      - Locations
    delete:
      summary: Delete Location
      description: Deletes an existing location in the system.
      operationId: deleteLocation
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
      - Locations
  "/locations/{location_id}/nearby/":
    get:
      summary: Find Nearby Locations
      description: This endpoint retrieves all locations that are near the specified location.
      operationId: findNearbyLocations
      parameters:
        - name: Accept
          in: header
          type: string
          required: true
          default: 'application/vnd.ohanapi+json; version=1'
        - name: location_id
          in: path
          type: string
          required: true
        - in: query
          name: radius
          description: Default in miles is 0.5, minimum is 0.1.
          type: string
        - in: query
          name: page
          description: The particular page of results. Default is 1.
          type: string
        - in: query
          name: per_page
          description: Amount of locations to return per page.
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
      - Locations
  "/locations/{location_id}/address/":
    post:
      summary: Location Address
      description: Creates a new address for a location
      operationId: createLocationAddress
      parameters:
        - name: location_id
          in: path
          type: string
          required: true      
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/address"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/address"
      tags:
      - Locations
  "/locations/{location_id}/address/{address_id}/":
    patch:
      summary: Update Location Address
      description: Updates an existing address for a location in the system.
      operationId: updateLocationAddress
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: address_id
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/address"
      tags:
      - Locations
    delete:
      summary: Delete Location Address
      description: Deletes an existing address for a location in the system.
      operationId: deleteLocationAddress
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: address_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/address"
      tags:
      - Locations
  "/locations/{location_id}/mail_address/":
    post:
      summary: Location Mailing Address
      description: Creates a new mailing address for a location
      operationId: createLocationMailingAddress
      parameters:
        - name: location_id
          in: path
          type: string
          required: true      
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/mailing_address"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/mailing_address"
      tags:
      - Locations
  "/locations/{location_id}/mail_address/{mail_address_id}/":
    patch:
      summary: Update Location Mailing Address
      description: Updates an existing mailing address for a location in the system.
      operationId: updateLocationMailingAddress
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: mail_address_id
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/mailing_address"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/mailing_address"
      tags:
      - Locations
    delete:
      summary: Delete Location Mailing Address
      description: Deletes an existing mailing address for a location in the system.
      operationId: deleteLocationMailingAddress
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: mail_address_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/mailing_address"
      tags:
      - Locations
  "/locations/{location_id}/contacts/":
    get:
      summary: Get Location Contacts
      description: Retrieve all of the contacts for a location
      operationId: retrieveLocationContacts
      parameters:
        - name: location_id
          in: path
          type: string
          required: true      
        - name: page
          in: query
          type: string
          required: false
        - name: per_page
          in: query
          type: string
          required: false
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/contact"
      tags:
      - Locations
    post:
      summary: Create Location Contacts
      description: Creates a new contact for a location
      operationId: createLocationContact
      parameters:
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/contact"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/contact"
      tags:
      - Locations
  "/locations/{location_id}/contacts/{contact_id}/":
    patch:
      summary: Update Location Contact
      description: Updates an existing contact for a location.
      operationId: updateLocationContact
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: contact_id
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/contact"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/contact"
      tags:
      - Locations
    delete:
      summary: Delete Location Contact
      description: Deletes an existing contact for a location.
      operationId: deleteLocationContact
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: contact_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/contact"
      tags:
      - Locations
  "/locations/{location_id}/phones/":
    post:
      summary: Create Location Phone
      description: Creates a new phone for a location
      operationId: createLocationPhone
      parameters:
        - name: location_id
          in: path
          type: string
          required: true      
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/phone"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/phone"
      tags:
      - Locations
  "/locations/{location_id}/phones/{phone_id}/":
    patch:
      summary: Update Location Phone
      description: Updates an existing phone for a location.
      operationId: updateLocationPhone
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: phone_id
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/phone"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/phone"
      tags:
      - Locations
    delete:
      summary: Delete Location Phone
      description: Deletes an existing phone for a location.
      operationId: deleteLocationPhone
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: phone_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/phone"
      tags:
      - Locations
  "/locations/{location_id}/services/":
    get:
      summary: Services
      description: Retrieve all services for this location
      operationId: retrieveLocationServices
      parameters:
        - name: Accept
          in: header
          type: string
          required: true
          default: 'application/vnd.ohanapi+json; version=1'
        - name: location_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/service"
      tags:
      - Locations
    post:
      summary: Create Location Service
      description: Creates a new service for a location
      operationId: createLocationService
      parameters:
        - name: location_id
          in: path
          type: string
          required: true      
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/phone"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/phone"
      tags:
      - Locations
  "/locations/{location_id}/services/{service_id}/":
    patch:
      summary: Update Location Service
      description: Updates an existing service for a location.
      operationId: updateLocationService
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: service_id
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/service"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/service"
      tags:
      - Locations
    delete:
      summary: Delete Location Service
      description: Deletes an existing service for a location.
      operationId: deleteLocationService
      parameters:
        - name: location_id
          in: path
          type: string
          required: true
        - name: service_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/service"
      tags:
      - Locations
  "/organizations/":
    get:
      summary: Organizations
      description: Retrieve all of the organizations available in this database.
      operationId: retrieveLOrganizations
      parameters:
        - name: Accept
          in: header
          type: string
          required: true
          default: 'application/vnd.ohanapi+json; version=1'
        - name: page
          in: query
          type: string
          required: false
        - name: per_page
          in: query
          type: string
          required: false
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/organization"
      tags:
      - Organizations
    post:
      summary: Organizations
      description: Creates a new organization in the system.
      operationId: createOrganizations
      parameters:
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/organization"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/organization"
      tags:
      - Organizations
  "/organizations/{organization_id}/":
    get:
      summary: Organizations
      description: Retrieve all of the organizations available in this database.
      operationId: retrieveLOrganization
      parameters:
        - name: organization_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/organization"
      tags:
      - Organizations
    patch:
      summary: Organizations
      description: Updates an existing organization in the system.
      operationId: updateOrganization
      parameters:
        - name: organization_id
          in: path
          type: string
          required: true
        - name: body
          in: body
          schema:
            type: array
            items:
              "$ref": "#/definitions/organization"
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/organization"
      tags:
      - Organizations
    delete:
      summary: Organizations
      description: Deletes an existing organization in the system.
      operationId: deleteOrganization
      parameters:
        - name: organization_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/organization"
      tags:
      - Organizations
  "/organizations/{organization_id}/locations/":
    get:
      summary: Organization Locations
      description: This endpoint retrieves all locations that belong to a particular
        organization.
      operationId: retrieveLOrganizationLocations
      parameters:
        - name: Accept
          in: header
          type: string
          required: true
          default: 'application/vnd.ohanapi+json; version=1'
        - name: organization_id
          in: path
          type: string
          required: true
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
      - Organizations
  "/search/":
    get:
      summary: Search
      description: This endpoint retrieves all locations that match the criteria based on the parameters below. Multiple parameters can be used at the same time, separated by an ampersand (&).
      operationId: searchLocations
      parameters:
        - name: Accept
          in: header
          type: string
          required: true
          default: 'application/vnd.ohanapi+json; version=1'
        - in: query
          name: category
          type: string
        - in: query
          name: email
          type: string
        - in: query
          name: keyword
          type: string
        - in: query
          name: language
          type: string
        - in: query
          name: lat_lng
          type: string
        - in: query
          name: location
          type: string
        - in: query
          name: org_name
          type: string
        - in: query
          name: radius
          type: string
        - in: query
          name: service_area
          type: string
        - in: query
          name: status
          type: string
        - in: query
          name: page
          type: string
        - in: query
          name: per_page
          type: string
      responses:
        '200':
          description: Successful response
          schema:
            type: array
            items:
              "$ref": "#/definitions/location"
      tags:
      - Search
definitions:
  location:
    properties:
      id:
        description: 'Each location must have a unique identifier.'
        type: string
      organization_id:
        description: 'Each location must belong to a single organization. The identifier of the organization should be given here.'
        type: string
      name:
        description: 'The name of the location.'
        type: string
      alternate_name:
        description: 'An alternative name for the location.'
        type: string
      description:
        description: 'A description of this location.'
        type: string
      transportation:
        description: 'A description of the access to public or private transportation to and from the location.'
        type: string
      latitude:
        description: 'Y coordinate of location expressed in decimal degrees in WGS84 datum.'
        type: string
      longitude:
        description: 'X coordinate of location expressed in decimal degrees in WGS84 datum.'
        type: string
  organization:
    properties:
      id:
        description: 'Each organization must have a unique identifier.'
        type: string
      name:
        description: 'The official or public name of the organization.'
        type: string
      alternate_name:
        description: 'Alternative or commonly used name for the organization.'
        type: string
      description:
        description: 'A brief summary about the organization. It can contain markup such as HTML or Markdown.'
        type: string
      email:
        description: 'The contact e-mail address for the organization.'
        type: string
      url:
        description: 'The URL (website address) of the organization.'
        type: string
      tax_status:
        description: 'Government assigned tax designation for for tax-exempt organizations.'
        type: string
      tax_id:
        description: 'A government issued identifier used for the purpose of tax administration.'
        type: string
      year_incorporated:
        description: 'The year in which the organization was legally formed.'
        type: string
      legal_status:
        description: 'The legal status defines the conditions that an organization is operating under; e.g. non-profit, private corporation or a government organization.'
        type: string
  address:
    properties:
      id:
        description: 'Each physical address must have a unique identifier.'
        type: string
      location_id:
        description: 'The identifier of the location for which this is the address.'
        type: string
      attention:
        description: 'The person or entity whose attention should be sought at the location.'
        type: string
      address_1:
        description: 'The first line of the address.'
        type: string
      address_2:
        description: 'The second line of the address.'
        type: string
      address_3:
        description: 'The third line of the address.'
        type: string
      address_4:
        description: 'The fourth line of the address.'
        type: string
      city:
        description: 'The city in which the address is located.'
        type: string
      state_province:
        description: 'The state or province in which the address is located.'
        type: string
      postal_code:
        description: 'The postal code for the address.'
        type: string
      country:
        description: 'The country in which the address is located. This should be given as an ISO 3361-1 country code (two letter abbreviation).'
        type: string
  mailing_address:
    properties:
      id:
        description: 'Each postal address must have a unique identifier.'
        type: string
      location_id:
        description: 'The identifier of the location for which this is the postal address.'
        type: string
      attention:
        description: 'The person or entity for whose attention mail should be marked.'
        type: string
      address_1:
        description: 'The first line of the address.'
        type: string
      address_2:
        description: 'The second line of the address.'
        type: string
      address_3:
        description: 'The third line of the address.'
        type: string
      address_4:
        description: 'The fourth line of the address.'
        type: string
      city:
        description: 'The city in which the address is located.'
        type: string
      state_province:
        description: 'The state or province in which the address is located.'
        type: string
      postal_code:
        description: 'The postal code for the address.'
        type: string
      country:
        description: 'The country in which the address is located.'
        type: string
  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
      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
      taxonomy_ids:
        description: 'A comma separated list of identifiers from the taxonomy table.'
        type: string
  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
      number:
        description: 'The phone number.'
        type: string
      extension:
        description: 'The extension of the phone number.'
        type: number
      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
  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
      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