swagger.yaml

swagger: '2.0'
info:
  title: HR API
  description: |
    API to retrieve the departments, position titles, and ID's tied to a department and business center.
  version: '1.0'
  license:
    name: GNU Affero General Public License Version 3
    url: http://www.gnu.org/licenses/agpl-3.0.en.html
externalDocs:
  description: GitHub Repository
  url: https://github.com/osu-mist/hr-api
schemes:
  - https
produces:
  - application/json
basePath: /v1/hr
paths:
  /positions:
    get:
      summary: List positions
      description: List position (job) titles and numbers in a single business center and department.
      parameters:
        - in: query
          name: type
          description: The type of positions to list. Currently the API only supports "student" positions.
          required: true
          type: string
        - $ref: '#/parameters/businessCenter'
        - $ref: '#/parameters/pretty'
      responses:
        200:
          description: List of positions
          schema:
            $ref: "#/definitions/PositionsResultObject"
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /departments:
    get:
      summary: List departments
      description: Return org code and org description (departments) for a single business center
      parameters:
        - $ref: '#/parameters/businessCenter'
        - $ref: '#/parameters/pretty'
      responses:
        200:
          description: List of departments
          schema:
            $ref: "#/definitions/DepartmentsResultObject"
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /locations:
    get:
      summary: List locations
      description: Return a list of HR locations that can be related to a job record, including minimum wages if applicable.
      parameters:
        - in: query
          name: state
          description: "Filter by state code. Use ANSI standard INCITS 38:2009 for state codes."
          required: false
          type: string
        - $ref: '#/parameters/date'
        - $ref: '#/parameters/pretty'
      responses:
        200:
          description: List of locations
          schema:
            $ref: "#/definitions/LocationsResultObject"
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'
  /locations/{id}:
    get:
      summary: Get location by ID
      description: Return a single HR location that can be related to a job record, including minimum wages if applicable.
      parameters:
        - in: path
          name: id
          description: ID of location.
          required: true
          type: string
        - $ref: '#/parameters/date'
        - $ref: '#/parameters/pretty'
      responses:
        200:
          description: Location
          schema:
            $ref: "#/definitions/LocationResultObject"
        400:
          description: Bad request
          schema:
            $ref: '#/definitions/Error'
        404:
          description: Location not found
          schema:
            $ref: '#/definitions/Error'
        500:
          description: Internal Server Error
          schema:
            $ref: '#/definitions/Error'

parameters:
  pretty:
    name: pretty
    in: query
    type: boolean
    required: false
    description: If true, JSON response will be pretty-printed
  businessCenter:
    name: businessCenter
    in: query
    description: "4-character business center name"
    required: true
    type: string
  date:
    name: date
    in: query
    description: "Date to search by for minimum wage data. Minimum wage depends on the date. Example: '2018-12-31'"
    required: false
    type: string
    format: date
    default: The current date

definitions:
  Error:
    properties:
      status:
        type: integer
        description: HTTP status code.
      developerMessage:
        type: string
        description: An error string aimed at developers.
      userMesage:
        type: string
        description: An error string aimed at end users.
      code:
        type: integer
        description: Error code.
      details:
        type: string
        description: A link to further information about the error.
  PositionsResultObject:
    properties:
      data:
        type: array
        items:
          properties:
            id:
              type: string
              example: "C12345"
            type:
              type: string
              example: position
            attributes:
              properties:
                title:
                  type: string
                  description: Position title
                class:
                  type: string
                  description: Position class
                businessCenter:
                  type: string
                  description: Name of the business center
                positionNumber:
                  type: string
                  description: Position number
                  example: "C12345"
                organizationCode:
                  type: string
                  description: Numeric orgCode for the department
                lowSalaryPoint:
                  type: number
                  format: float
                  description: Low point for position salary
                  example: 10.5
                highSalaryPoint:
                  type: number
                  format: float
                  description: High point for position salary
                  example: 15.25
                nationalOccupationCode:
                  type: string
                  description: Numeric national occupation code
                  example: "1234"
                nationalOccupationCodeDescription:
                  type: string
                  description: Description of nationalOccupationCode
                  example: "Colleges/Schools Professionals"

  DepartmentsResultObject:
    properties:
      data:
        type: array
        items:
          properties:
            id:
              type: string
              example: "123456"
            type:
              type: string
              example: department
            attributes:
              properties:
                name:
                  type: string
                  description: Name of the department usually referred to as orgDescription.
                businessCenter:
                  type: string
                  description: Name of the business center
                organizationCode:
                  type: string
                  example: "123456"
                  description: Numeric orgCode for the department
  LocationsResultObject:
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/LocationResourceObject'
  LocationResultObject:
    properties:
      data:
        $ref: '#/definitions/LocationResourceObject'
  LocationResourceObject:
    properties:
      id:
        type: string
        example: "40"
      type:
        type: string
        example: location
      attributes:
        properties:
          name:
            type: string
          city:
            type: string
            example: Corvallis
          county:
            type: string
            example: Benton County
          state:
            type: string
            example: Oregon
          stateCode:
            type: string
            description: "State code/abbreviation which follows ANSI standard INCITS 38:2009"
            example: OR
          minimumWageClassification:
            type: string
            description: Classification of location related to minimum wage. This classification affects the value of minimum wage for a given date.
            enum:
              - Standard
              - Nonurban
              - Urban
            example: Standard
          minimumWage:
            type: number
            format: float
            description: |
              Minimum wage for location.
              Currently, minimum wage is only available for Oregon locations.
              This value can be affected by the date query parameter.
            example: 10.25
          minimumWageDate:
            type: string
            format: date
            description: Date used to determine minimum wage.