openapi: 3.1.0
info:
  title: INIAD 教育用 IoT API
  version: v1
tags: []
paths:
  /api/v1/doorlocks/{room_number}:
    get:
      operationId: Doorlocks_list
      summary: 電気錠の一覧取得
      description: 指定した部屋の電気錠の URL を一覧で返す
      parameters:
        - name: room_number
          in: path
          required: true
          description: 部屋番号
          schema:
            $ref: '#/components/schemas/Models.RoomNumber'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
        '400':
          description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.BadRequestError'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '403':
          description: 対象デバイスへのアクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ForbiddenError'
        '404':
          description: 対象が存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.NotFoundError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
  /api/v1/doorlocks/{room_number}/{item_number}:
    get:
      operationId: Doorlocks_get
      summary: 電気錠情報の取得
      description: 指定した部屋の指定した番号の電気錠の読み取り値を返す
      parameters:
        - name: room_number
          in: path
          required: true
          description: 部屋番号
          schema:
            $ref: '#/components/schemas/Models.RoomNumber'
        - name: item_number
          in: path
          required: true
          description: デバイス番号
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.Doorlock'
        '400':
          description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.BadRequestError'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '403':
          description: 対象デバイスへのアクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ForbiddenError'
        '404':
          description: 対象が存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.NotFoundError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
    put:
      operationId: Doorlocks_update
      summary: 電気錠の開錠・施錠
      description: 指定した部屋の指定した番号の電気錠を開錠・施錠する
      parameters:
        - name: room_number
          in: path
          required: true
          description: 部屋番号
          schema:
            $ref: '#/components/schemas/Models.RoomNumber'
        - name: item_number
          in: path
          required: true
          description: デバイス番号
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.Doorlock'
        '400':
          description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.BadRequestError'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '403':
          description: 対象デバイスへのアクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ForbiddenError'
        '404':
          description: 対象が存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.NotFoundError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                locked:
                  type: boolean
                  description: ドア錠の施錠状態
                  examples:
                    - true
              required:
                - locked
  /api/v1/iccards:
    get:
      operationId: ICCards_list
      summary: IC カード情報の取得
      description: 自分の IC カードに関する情報を取得する
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Models.ICCard'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
    post:
      operationId: ICCards_register
      summary: IC カードの登録
      description: 自分の IC カード登録を追加する
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ICCard'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                uid:
                  type: string
                  description: カード ID (大文字 16 進数)
                  examples:
                    - 0114A5B2C3D4E5F6
                comment:
                  type: string
                  description: IC カードに対するコメント
                  examples:
                    - comment
              required:
                - uid
                - comment
    delete:
      operationId: ICCards_delete
      summary: IC カードの削除
      description: 自分の IC カード登録を削除する
      parameters: []
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
  /api/v1/lights/{room_number}:
    get:
      operationId: Lights_list
      summary: 照明の一覧取得
      description: 指定した部屋の照明の URL を一覧で返す
      parameters:
        - name: room_number
          in: path
          required: true
          description: 部屋番号
          schema:
            $ref: '#/components/schemas/Models.RoomNumber'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: uri
        '400':
          description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.BadRequestError'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '403':
          description: 対象デバイスへのアクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ForbiddenError'
        '404':
          description: 対象が存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.NotFoundError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
  /api/v1/lights/{room_number}/{item_number}:
    get:
      operationId: Lights_get
      summary: 照明情報の取得
      description: 指定した部屋の指定した番号の照明の読み取り値を返す
      parameters:
        - name: room_number
          in: path
          required: true
          description: 部屋番号
          schema:
            $ref: '#/components/schemas/Models.RoomNumber'
        - name: item_number
          in: path
          required: true
          description: デバイス番号
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.Light'
        '400':
          description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.BadRequestError'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '403':
          description: 対象デバイスへのアクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ForbiddenError'
        '404':
          description: 対象が存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.NotFoundError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
    put:
      operationId: Lights_update
      summary: 照明の変更
      description: 指定した部屋の指定した番号の照明を変更する
      parameters:
        - name: room_number
          in: path
          required: true
          description: 部屋番号
          schema:
            $ref: '#/components/schemas/Models.RoomNumber'
        - name: item_number
          in: path
          required: true
          description: デバイス番号
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.Light'
        '400':
          description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.BadRequestError'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '403':
          description: 対象デバイスへのアクセス権限がない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ForbiddenError'
        '404':
          description: 対象が存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.NotFoundError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  allOf:
                    - $ref: '#/components/schemas/Models.LightMode'
                  description: 照明の状態。`modes` のうちいずれかの値を指定する
                  examples:
                    - full
              required:
                - mode
  /api/v1/locker:
    get:
      operationId: Locker_get
      summary: ロッカー情報の取得
      description: 自分のロッカーに関する情報を取得する
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.Locker'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
  /api/v1/locker/open:
    post:
      operationId: Locker_open
      summary: ロッカーの開錠
      description: 自分のロッカーを開ける。開けたロッカーに関する情報が返る
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.Locker'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
  /api/v1/sensors/{room_number}:
    get:
      operationId: Sensors_get
      summary: センサ情報の取得
      description: 指定した部屋のセンサ情報を取得する
      parameters:
        - name: room_number
          in: path
          required: true
          description: 部屋番号
          schema:
            $ref: '#/components/schemas/Models.RoomNumber'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Models.Sensor'
        '400':
          description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.BadRequestError'
        '401':
          description: 認証に失敗 (資格情報の欠如または誤り)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.UnauthorizedError'
        '404':
          description: 対象が存在しない
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.NotFoundError'
        '503':
          description: レート制限、または INIAD Wi-Fi 外からのアクセス
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Models.ServiceUnavailableError'
security:
  - BasicAuth: []
components:
  schemas:
    Models.BadRequestError:
      type: object
      required:
        - status
        - description
      properties:
        status:
          type: string
          enum:
            - error
          description: 常に `error`
        description:
          type: string
          description: エラーの内容
      description: リクエストが不正 (パラメータの型・桁数違反やボディの不備など)
    Models.Doorlock:
      type: object
      required:
        - open
        - locked
        - room_num
        - item_num
        - device_type
      properties:
        open:
          type: boolean
          description: ドアの開閉状態
        locked:
          type: boolean
          description: ドア錠の施錠状態
        room_num:
          allOf:
            - $ref: '#/components/schemas/Models.RoomNumber'
          description: 設置されている部屋の番号
        item_num:
          type: integer
          format: int32
          description: 設置されている部屋におけるデバイス番号
        device_type:
          type: string
          enum:
            - doorlock
          description: デバイスの種類
      description: 電気錠情報
      examples:
        - open: false
          locked: true
          room_num: '3201'
          item_num: 1
          device_type: doorlock
    Models.ForbiddenError:
      type: object
      required:
        - status
        - description
      properties:
        status:
          type: string
          enum:
            - error
          description: 常に `error`
        description:
          type: string
          description: エラーの内容
      description: 対象デバイスへのアクセス権限がない
    Models.ICCard:
      type: object
      required:
        - id
        - uid
        - comment
      properties:
        id:
          type: integer
          format: int32
          description: 登録 ID
        uid:
          type: string
          description: カード ID (大文字 16 進数)
        comment:
          type: string
          description: IC カードに対するコメント
      description: IC カード情報
      examples:
        - id: 1
          uid: 0114A5B2C3D4E5F6
          comment: comment
    Models.Light:
      type: object
      required:
        - mode
        - modes
        - room_num
        - item_num
        - device_type
      properties:
        mode:
          allOf:
            - $ref: '#/components/schemas/Models.LightMode'
          description: 照明の現在状態。`modes` のうちいずれかの値となる
        modes:
          type: array
          items:
            $ref: '#/components/schemas/Models.LightMode'
          description: '`mode` が取り得る値の種類。照明デバイスの種類によって変化する'
        room_num:
          allOf:
            - $ref: '#/components/schemas/Models.RoomNumber'
          description: 設置されている部屋の番号。屋上の場合は `6000`
        item_num:
          type: integer
          format: int32
          description: 設置されている部屋におけるデバイス番号
        device_type:
          type: string
          enum:
            - light
          description: デバイスの種類
      description: 照明情報
      examples:
        - mode: full
          modes:
            - full
            - 'off'
          room_num: '3201'
          item_num: 1
          device_type: light
    Models.LightMode:
      type: string
      enum:
        - full
        - 'off'
        - dim
        - lv6
        - lv5
        - lv4
        - lv3
        - lv2
        - lv1
      description: 照明の状態
    Models.Locker:
      type: object
      required:
        - name
        - floor
      properties:
        name:
          type: string
          description: ロッカーの名前 (番号)
        floor:
          type: integer
          format: int32
          description: ロッカーのある階
      description: ロッカー情報
      examples:
        - name: '326605'
          floor: 3
    Models.NotFoundError:
      type: object
      required:
        - status
        - description
      properties:
        status:
          type: string
          enum:
            - error
          description: 常に `error`
        description:
          type: string
          description: エラーの内容
      description: 対象が存在しない
    Models.RoomNumber:
      type: string
      pattern: ^[0-9]{4}$
      description: 部屋番号 (4 桁の数字)
      examples:
        - '3201'
    Models.Sensor:
      type: object
      required:
        - room_num
        - sensor_type
        - value
      properties:
        room_num:
          allOf:
            - $ref: '#/components/schemas/Models.RoomNumber'
          description: 部屋番号
        sensor_type:
          allOf:
            - $ref: '#/components/schemas/Models.SensorType'
          description: センサの種類
        value:
          anyOf:
            - type: number
              format: double
            - type: 'null'
          description: 計測値。センサが値を取得できない場合は `null`
      description: センサの計測値
      examples:
        - room_num: '3201'
          sensor_type: temperature
          value: 26
    Models.SensorType:
      type: string
      enum:
        - temperature
        - humidity
        - illuminance
        - airpressure
      description: センサの種類
    Models.ServiceUnavailableError:
      type: object
      required:
        - status
        - description
      properties:
        status:
          type: string
          enum:
            - error
          description: 常に `error`
        description:
          type: string
          description: エラーの内容
      description: レート制限、または INIAD Wi-Fi 外からのアクセス
    Models.UnauthorizedError:
      type: object
      required:
        - status
        - description
      properties:
        status:
          type: string
          enum:
            - error
          description: 常に `error`
        description:
          type: string
          description: エラーの内容
      description: 認証に失敗 (資格情報の欠如または誤り)
  securitySchemes:
    BasicAuth:
      type: http
      scheme: Basic
servers:
  - url: https://edu-iot.iniad.org
    variables: {}
  - url: https://api.iniad.org
    variables: {}