swagger.yaml

swagger: "2.0"
info:
  title: Academic Disciplines
  description: Get academic disciplines offered by the university, including majors, minors, and concentrations.
  version: "1"
  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/academic-disciplines-api
schemes:
  - https
host: api.oregonstate.edu
basePath: /v1
produces:
  - application/json
security:
  - OAuth2:
      - full
paths:
  /academic-disciplines:
    get:
      tags:
      - disciplines
      operationId: getDisciplines
      description: "Get a list of majors, minors, and concentrations. Filter by query parameters."
      parameters:
        - name: major
          in: query
          description: >
            If true, disciplines that are not majors will be excluded.
          type: boolean
          required: false
        - name: minor
          in: query
          description: >
            If true, disciplines that are not minors will be excluded.
          type: boolean
          required: false
        - name: concentration
          in: query
          description: >
            If true, disciplines that are not concentrations will be excluded.
          type: boolean
          required: false
        - name: department
          in: query
          description: Filter by department code.
          type: string
          required: false
        - $ref: '#/parameters/pretty'
      responses:
        "200":
          description: Successful response
          schema:
            $ref: "#/definitions/DisciplineResultObject"
        "400":
          description: Bad request
          schema:
            $ref: "#/definitions/Error"
  /academic-disciplines/{id}:
    get:
      tags:
      - disciplines
      operationId: getDisciplineByID
      description: "Get a concentration by code/ID"
      parameters:
        - name: id
          in: path
          description: "ID/code of discipline to retrieve."
          type: string
          required: true
        - $ref: '#/parameters/pretty'
      responses:
        "200":
          description: Successful response
          schema:
            $ref: "#/definitions/DisciplineResultObject"
        "404":
          description: Not found
          schema:
            $ref: "#/definitions/Error"
parameters:
  pretty:
    name: pretty
    in: query
    type: boolean
    required: false
    description: If true, JSON response will be pretty-printed
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: https://api.oregonstate.edu/oauth2/token
    scopes:
      full: Full access to the API
definitions:
  DisciplineResultObject:
    properties:
      data:
        type: array
        items:
          $ref: "#/definitions/Presentation"
  Presentation:
    properties:
      id:
        type: string
        description: Discipline code
      type:
        type: string
      attributes:
        $ref: "#/definitions/DisciplineAttributes"
  DisciplineAttributes:
    properties:
      description:
        type: string
        description: Description of discipline.
      descriptionLong:
        type: string
        description: Long description of discipline.
      major:
        type: boolean
      minor:
        type: boolean
      concentration:
        type: boolean
      department:
        type: string
        description: Department code
      cipcCode:
        type: string
  Error:
    type: object
    properties:
      status:
        type: integer
        format: int32
        description: HTTP status code.
      developerMessage:
        type: string
        description: An error string aimed at developers.
      userMessage:
        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.