openapi: 3.0.3
info:
  title: LionSpaceFIS REST API
  description: >-
    Public REST API from the Penn State Office of Physical Plant (OPP) exposing
    the university's facilities and space data, the successor to the legacy FIS
    Facilities Information System. Exposes buildings, rooms, campuses,
    buildingEvents, and roomEvents entities with filtering, wildcard, and
    comparison operators, plus a health endpoint. This OpenAPI description was
    reconstructed from the public HTML documentation and from live, observed
    responses of the running service (appVersion 1.14.0); the provider does not
    publish a machine-readable specification of its own.
  version: 1.14.0
  contact:
    name: Penn State Office of Physical Plant
    url: https://apps.opp.psu.edu/fis-api/
servers:
  - url: https://apps.opp.psu.edu/fis-api/v1
    description: Production v1 API
  - url: https://apps.opp.psu.edu/fis-api
    description: Service root (health endpoint)
tags:
  - name: Campuses
    description: Penn State campus reference data.
  - name: Buildings
    description: University buildings and their facility attributes.
  - name: Rooms
    description: Rooms within buildings.
  - name: Events
    description: Change events for buildings and rooms.
  - name: Health
    description: Service health and status.
paths:
  /campuses:
    get:
      tags: [Campuses]
      summary: List campuses
      description: Returns the list of Penn State campuses known to the facilities system.
      operationId: listCampuses
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of campuses.
          headers:
            X-Total-Count:
              description: Total number of matching records (pagination metadata).
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Campus'
  /buildings:
    get:
      tags: [Buildings]
      summary: List buildings
      description: >-
        Returns buildings with their facility attributes. Supports filtering on
        properties using comparison operators such as :eq, :ne, :ge, :le, :gt,
        :lt, :like, and :ilike (e.g. name:ilike=lab).
      operationId: listBuildings
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: name
          in: query
          description: Filter by building name, optionally with an operator suffix.
          required: false
          schema:
            type: string
        - name: status
          in: query
          description: Filter by building status (e.g. ACTV).
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of buildings.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Building'
  /rooms:
    get:
      tags: [Rooms]
      summary: List rooms
      description: >-
        Returns rooms within buildings. Supports filtering by building id, floor,
        and other properties using the same comparison operators as buildings.
      operationId: listRooms
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - name: floor
          in: query
          description: Filter by room floor.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: A list of rooms.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Room'
  /buildingEvents:
    get:
      tags: [Events]
      summary: List building change events
      description: >-
        Returns change events for buildings. Events are reported once daily to
        avoid redundant updates. Event codes include A (add) and U (update).
      operationId: listBuildingEvents
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of building change events.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BuildingEvent'
  /roomEvents:
    get:
      tags: [Events]
      summary: List room change events
      description: >-
        Returns change events for rooms. Events are reported once daily. Event
        codes include A (add) and U (update), with oldValue/newValue and the
        changed fieldName for updates.
      operationId: listRoomEvents
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: A list of room change events.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RoomEvent'
  /health:
    servers:
      - url: https://apps.opp.psu.edu/fis-api
    get:
      tags: [Health]
      summary: Service health
      description: Returns the service status and dependency health checks.
      operationId: getHealth
      responses:
        '200':
          description: Service health information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Health'
components:
  parameters:
    limit:
      name: limit
      in: query
      description: Maximum number of records to return.
      required: false
      schema:
        type: integer
        minimum: 1
    offset:
      name: offset
      in: query
      description: Number of records to skip for pagination.
      required: false
      schema:
        type: integer
        minimum: 0
  schemas:
    Campus:
      type: object
      properties:
        id:
          type: string
          example: UP
        maximoCampusCode:
          type: string
          example: UP
        lionPathCampusCode:
          type: string
          example: UP
        maximoCode:
          type: string
          example: UP
        lionPathCode:
          type: string
          example: AE
        name:
          type: string
          example: University Park
    LatLong:
      type: object
      properties:
        latitude:
          type: number
          format: double
          example: 40.79974
        longitude:
          type: number
          format: double
          example: -77.86252
    Building:
      type: object
      properties:
        id:
          type: string
          example: '0402000'
        name:
          type: string
          example: Wartik Laboratory (Dr Thomas)
        abbreviation:
          type: string
          example: Wartik Lab
        maximoName:
          type: string
          example: WARTIK LAB
        function:
          type: string
          example: '30500'
        buildingFunctionCat:
          type: string
          example: EG
        status:
          type: string
          example: ACTV
        county:
          type: string
          example: Centre
        address:
          type: string
          example: 360 SCIENCE DR
        city:
          type: string
          example: UNIVERSITY PARK
        state:
          type: string
          example: PA
        zipCode:
          type: string
          example: '16802'
        businessAreaKey:
          type: string
          example: '6390'
        isWorkspace:
          type: boolean
          example: true
        facilityCoordinators:
          type: string
          nullable: true
        capacity:
          type: integer
          example: 178
        occupancy:
          type: integer
          example: 69
        campus:
          $ref: '#/components/schemas/Campus'
        lastUpdateDate:
          type: string
          format: date
          example: '2026-04-29'
        dateInactivated:
          type: string
          format: date
          nullable: true
        latLong:
          $ref: '#/components/schemas/LatLong'
    RoomType:
      type: object
      properties:
        id:
          type: string
          example: '955'
        description:
          type: string
          example: Apartment Service
    BuildingRef:
      type: object
      properties:
        id:
          type: string
          example: '0290012'
    Room:
      type: object
      properties:
        id:
          type: string
          example: 0290012-1-109D
        number:
          type: string
          example: 109D
        name:
          type: string
          nullable: true
        floor:
          type: string
          example: '1'
        floorVerticalOrder:
          type: integer
          nullable: true
        netArea:
          type: number
          format: double
          example: 12.09
        fireCodeCapacity:
          type: integer
          example: 0
        capacity:
          type: integer
          example: 0
        occupancy:
          type: integer
          example: 0
        photoUrl:
          type: string
          nullable: true
        collegeNetKey:
          type: string
          nullable: true
        businessAreaKey:
          type: string
          example: '6530'
        principalInvestigators:
          type: string
          nullable: true
        occupants:
          type: string
          nullable: true
        facilityCoordinators:
          type: string
          nullable: true
        maximoLocation:
          type: string
          example: 0290012-109D
        lastUpdateDate:
          type: string
          format: date
          example: '2022-03-28'
        dateInactivated:
          type: string
          format: date
          nullable: true
        campus:
          $ref: '#/components/schemas/Campus'
        latLong:
          $ref: '#/components/schemas/LatLong'
        building:
          $ref: '#/components/schemas/BuildingRef'
        type:
          $ref: '#/components/schemas/RoomType'
    BuildingEvent:
      type: object
      properties:
        event:
          type: string
          description: Event code (A = add, U = update).
          example: A
        oldValue:
          type: string
          nullable: true
        newValue:
          type: string
          nullable: true
        changeDate:
          type: string
          format: date
          example: '2021-05-28'
        fieldName:
          type: string
          nullable: true
        buildingId:
          type: string
          example: '0002000'
    RoomEvent:
      type: object
      properties:
        event:
          type: string
          description: Event code (A = add, U = update).
          example: U
        oldValue:
          type: string
          nullable: true
          example: '1'
        newValue:
          type: string
          nullable: true
          example: '0'
        changeDate:
          type: string
          format: date
          example: '2021-05-28'
        fieldName:
          type: string
          nullable: true
          example: OCCUPANCY
        roomId:
          type: string
          example: 0965002-G-164
    HealthDetail:
      type: object
      properties:
        name:
          type: string
          example: databaseConnectivity
        result:
          type: string
          example: OK
        time:
          type: integer
          example: 51
    Health:
      type: object
      properties:
        appVersion:
          type: string
          example: 1.14.0
        appStatus:
          type: string
          example: UP
        totalTime:
          type: integer
          example: 59
        details:
          type: array
          items:
            $ref: '#/components/schemas/HealthDetail'