openapi.yaml

swagger: '2.0'
info:
  title: Terms API
  description: Get information about terms
  version: v1
  license:
    name: GNU Affero General Public License Version 3
    url: http://www.gnu.org/licenses/agpl-3.0.en.html
  contact:
    name: IS Data Architecture Team
    url: https://is.oregonstate.edu/data-architecture
    email: isdataarchitecture@oregonstate.edu
schemes:
  - https
host: api.oregonstate.edu
basePath: /v1
externalDocs:
  description: GitHub Repository
  url: https://github.com/osu-mist/terms-api
produces:
  - application/json
consumes:
  - application/json
security:
  - OAuth2:
      - full
paths:
  /terms:
    get:
      summary: List all terms
      tags:
        - terms
      description: Get terms
      operationId: getTerms
      parameters:
        - $ref: '#/parameters/pageNumber'
        - $ref: '#/parameters/pageSize'
        - in: query
          name: academicYear
          description: Search terms by academic year. For example, 1819
          required: false
          type: string
          pattern: '^\d{4}$'
        - in: query
          name: calendarYear
          description: Search terms by calendar year. For example, 2019
          required: false
          type: string
          pattern: '^\d{4}$'
        - in: query
          name: financialAidYear
          description: Search terms by financial aid year. For example, 1819
          required: false
          type: string
          pattern: '^\d{4}$'
        - in: query
          name: date
          description: Search term by date. For example, 2019-01-01
          required: false
          type: string
          format: date
        - in: query
          name: postInterimTermDate
          description: Search the post-interim term for a specific date. For example, 2019-01-01
          required: false
          type: string
          format: date
        - in: query
          name: preInterimTermDate
          description: Search the pre-interim term for a specific date. For example, 2019-01-01
          required: false
          type: string
          format: date
        - in: query
          name: housingDate
          description: Search term by housing date. For example, 2019-01-01
          required: false
          type: string
          format: date
        - in: query
          name: registrationDate
          description: Search term by registration date. For example, 2019-01-01
          required: false
          type: string
          format: date
        - in: query
          name: status
          description: |
            Filter terms which contain at least one of the provided status:
            - `completed` - term has been completed
            - `current` - current term
            - `open` - terms that a student can register for
            - `not-open` - terms which are not open for registration yet
            - `post-interim` - post-interim term of the current date
            - `pre-interim` - pre-interim term of the current date
          required: false
          type: array
          collectionFormat: csv
          items:
            type: string
            enum: [completed, current, open, not-open, pre-interim, post-interim]
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/TermsResult'
        '400':
          description: Bad request
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResult'
  /terms/{termCode}:
    get:
      summary: Info for a specific term
      tags:
        - terms
      description: Get term by term code
      operationId: getTermByTermCode
      parameters:
        - name: termCode
          in: path
          description: 6-digit unique code
          required: true
          type: string
          pattern: '^\d{6}$'
      responses:
        '200':
          description: Successful response
          schema:
            $ref: '#/definitions/TermResult'
        '404':
          description: Term not found
          schema:
            $ref: '#/definitions/ErrorResult'
        '500':
          description: Internal server error
          schema:
            $ref: '#/definitions/ErrorResult'
parameters:
  pageNumber:
    name: page[number]
    in: query
    type: integer
    required: false
    description: Page number of results
    default: 1
    minimum: 1
  pageSize:
    name: page[size]
    in: query
    type: integer
    required: false
    description: Number of results to return
    default: 25
    maximum: 500
    minimum: 1
securityDefinitions:
  OAuth2:
    type: oauth2
    flow: application
    tokenUrl: https://api.oregonstate.edu/oauth2/token
    scopes:
      full: Full access to the API
definitions:
  Meta:
    properties:
      totalResults:
        type: integer
        description: Total number of results
        example: 10
      totalPages:
        type: integer
        description: Total number of pages
        example: 10
      currentPageNumber:
        type: integer
        description: Page number of the returned results
        example: 1
      currentPageSize:
        type: integer
        description: Number of results per page
        example: 25
  PaginationLinks:
    properties:
      self:
        type: string
        format: uri
        description: Self-link of current resource
      first:
        type: string
        format: uri
        description: The first page of data
      last:
        type: string
        format: uri
        description: The last page of data
      prev:
        type: string
        format: uri
        description: The previous page of data
      next:
        type: string
        format: uri
        description: The next page of data
  SelfLink:
    properties:
      self:
        type: string
        format: url
        description: Self-link of current resource
  TermResource:
    properties:
      id:
        type: string
        description: A 6-digit unique term code
        pattern: '^\d{6}$'
      type:
        type: string
        enum: [term]
      links:
        $ref: '#/definitions/SelfLink'
      attributes:
        properties:
          description:
            type: string
            description: Human readable academic term description
            example: Winter 2019
          season:
            type: string
            description: Season of the term
            example: Winter
            enum: [Fall, Winter, Summer, Spring]
          calendarYear:
            type: string
            description: A 4-digit calendar year
            pattern: '^\d{4}$'
            example: '2019'
          academicYear:
            type: string
            description: Academic year associated with this term. This is a 4-digit code
            pattern: '^\d{4}$'
            example: '1819'
          financialAidYear:
            type: string
            description: Aid year associated with this term. This is a 4-digit code. For example, for Summer 2018, the value would be 1819
            pattern: '^\d{4}$'
            example: '1819'
          startDate:
            type: string
            description: First day of classes in this term. Format is in YYYY-MM-DD
            format: date
            example: 2019-01-07
          endDate:
            type: string
            description: Last day of classes in this term. Format is in YYYY-MM-DD
            format: date
            example: 2019-03-22
          housingStartDate:
            type: string
            description: First day for meal plan and housing assignments. Format is in YYYY-MM-DD
            format: date
            example: 2019-01-06
          housingEndDate:
            type: string
            description: Last day for meal plan and housing assignments. Format is in YYYY-MM-DD
            format: date
            example: 2019-03-16
          registrationStartDate:
            type: string
            description: First day for general registration. Format is in YYYY-MM-DD
            format: date
            example: 2018-10-19
          registrationEndDate:
            type: string
            description: Last day for general registration. Format is in YYYY-MM-DD
            format: date
            example: 2019-03-15
          status:
            type: array
            description: The status of the term
            items:
              type: string
              enum: [completed, current, open, not-open, post-interim, pre-interim]
            example: [current, open]
  TermResult:
    properties:
      links:
        $ref: '#/definitions/SelfLink'
      data:
        $ref: '#/definitions/TermResource'
  TermsResult:
    properties:
      meta:
        $ref: '#/definitions/Meta'
      links:
        $ref: '#/definitions/PaginationLinks'
      data:
        type: array
        items:
          $ref: '#/definitions/TermResource'
  ErrorObject:
    properties:
      status:
        type: string
        description: HTTP status code
        example: '123'
      title:
        type: string
        description: A short, user readable summary of the error
        example: Not Found
      code:
        type: string
        description: An application-specific error code
        example: '1234'
      detail:
        type: string
        description: A long description of the error that may contain instance-specific details
      links:
        properties:
          about:
            type: string
            format: uri
            description: A link to further information about the error
            example: https://developer.oregonstate.edu/documentation/error-reference#1234
  ErrorResult:
    properties:
      errors:
        type: array
        items:
          $ref: '#/definitions/ErrorObject'