hsda-service-taxonomies-road-map-suggestion

hsda-service-taxonomies-road-map-suggestion.yaml

swagger: '2.0'
info:
  title: "HSDA"
  description: "HSDA Service Taxonomies Road Map Suggestion"
  termsOfService: "https://openreferral.org/documentation/"
  contact:
    name: Open Referral
    url: https://openreferral.org/
    email: info@openreferral.org
  license:
    name: Creative Commons Attribution Share-Alike 4.0
    url: https://creativecommons.org/licenses/by-sa/4.0/
  version: v1.2
host: example.com
basePath: /
schemes:
- http
produces:
- application/json
- application/xml
- text/csv
paths:
  /services/{service_id}/taxonomies/:
    get:
      summary: Get service
      description: Returns a specific service entry by Id
      operationId: getService
      parameters:
        - in: path
          required: true
          type: string
          name: service_id
          description: 'The unique service id.'
      responses:
        '200':
          description: Organization Response
          schema:
            type: array
            items:
              $ref: "#/definitions/taxonomy"
        '500':
          description: Error Response
          schema:
            type: array
            items:
              $ref: "#/definitions/error_response"
      tags:
      - Services
    post:
      summary: Add Service Taxonomy
      description: Adds an individual taxonomy to a service.
      operationId: AddServiceTaxonomy
      parameters:
        - in: path
          required: true
          type: string
          name: service_id
          description: 'The unique service id.'       
        - in: body
          name: body
          schema:
            $ref: "#/definitions/taxonomy"
      responses:
        '200':
          description: Service 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:
      - Services 
  /services/{service_id}/taxonomies/{taxonomy_id}/:
    delete:
      summary: Delete Service Taxonomy
      description: Returns a specific service entry by Id
      operationId: deleteServiceTaxonomy
      parameters:
        - in: path
          required: true
          type: string
          name: service_id
          description: 'The service id.'
        - 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:
      - Services      
  /services/complete/{service_id}/taxonomies/:
    get:
      summary: Get Service Taxonomies
      description: Returns all of the taxonomies for a service.
      operationId: getServiceCompleteTaxonomies
      parameters:
        - in: path
          required: true
          type: string
          name: service_id
          description: The service id.
      responses:
        '200':
          description: Service Complete Taxoomies Response
          schema:
            type: array
            items:
              $ref: "#/definitions/taxonomy"
        '500':
          description: Error Response
          schema:
            type: array
            items:
              $ref: "#/definitions/error_response"
      tags:
      - Services
    post:
      summary: Add Service Taxonomy
      description: Adds an individual taxonomy to a service.
      operationId: AddServiceCompleteTaxonomy
      parameters:
        - in: path
          required: true
          type: string
          name: service_id
          description: The service id.      
        - in: body
          name: body
          schema:
            $ref: "#/definitions/taxonomy"
      responses:
        '200':
          description: Contact Complete 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:
      - Services 
  /services/complete/{service_id}/taxonomies/{taxonomy_id}/:
    delete:
      summary: Delete Service Taxonomy
      description: Deletes a taxonomy from a service.
      operationId: deleteServiceCompleteTaxonomy
      parameters:
        - in: path
          required: true
          type: string
          name: service_id
          description: 'The service id.'
        - 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:
      - Services            
definitions:
  taxonomy:
    description: 'Describes a taxonomy object.'
    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
  error_response:
    description: 'Describes an HTTP error returned by the service'
    properties:
      code:
        description: 'Repeat the HTTP status code'
        type: integer
      message:
        description: 'A plain language message explaining the error'
        type: integer