mk6i-open-oscar-server/api.yml

openapi: 3.0.3
info:
  title: User Management API
  description: API that provides management functionality for Retro AIM Server operators.
  version: 1.0.0
paths:
  /user:
    get:
      summary: Get all users
      description: Retrieve a list of all user accounts.
      responses:
        '200':
          description: Successful response containing a list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      description: User's unique identifier.
                    screen_name:
                      type: string
                      description: User's AIM screen name or ICQ UIN.
                    is_icq:
                      type: boolean
                      description: If true, indicates an ICQ user instead of an AIM user.
    post:
      summary: Create a new user
      description: Create a new AIM or ICQ user account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - screen_name
                - password
              properties:
                screen_name:
                  type: string
                  description: The user's AIM screen name or ICQ UIN.
                password:
                  type: string
                  description: The user's password for account creation.
      responses:
        '201':
          description: User account created successfully.
        '400':
          description: Bad request. Invalid input data.
        '409':
          description: Conflict. A user with the specified screen name or ICQ UIN already exists.
    delete:
      summary: Delete a user
      description: Delete a user account specified by their screen name.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                screen_name:
                  type: string
                  description: The screen name of the user to delete.
      responses:
        '204':
          description: User deleted successfully.
        '404':
          description: User not found.

  /user/{screenname}/account:
    get:
      summary: Get account details for a specific screen name.
      description: Retrieve account details for a specific screen name.
      parameters:
      - name: screenname
        in: path
        description: User's AIM screen name or ICQ UIN.
        required: true
        type: string
      responses:
        '200':
          description: Successful response containing account details
          content:
            application/json:
              schema:
                type: object
                properties:
                    id:
                      type: string
                      description: User's unique identifier.
                    screen_name:
                      type: string
                      description: User's AIM screen name or ICQ UIN.
                    profile:
                      type: string
                      description: User's AIM profile HTML.
                    email_address:
                      type: string
                      description: User's email address
                    confirmed:
                      type: bool
                      description: User's account confirmation status
                    is_icq:
                      type: boolean
                      description: If true, indicates an ICQ user instead of an AIM user.
        '404':
          description: User not found.

  /user/{screenname}/icon:
    get:
      summary: Get AIM buddy icon for a screen name
      description: Retrieve account buddy icon for a specific screen name.
      parameters:
      - name: screenname
        in: path
        description: User's AIM screen name or ICQ UIN.
        required: true
        type: string
      responses:
        '200':
          description: Successful response containing buddy icon bytes
          content:
            image/gif:
              schema:
                type: string
                format: binary
        '404':
          description: User not found, or user has no buddy icon

  /session:
    get:
      summary: Get active sessions
      description: Retrieve a list of active sessions of logged in users.
      responses:
        '200':
          description: Successful response containing a list of active sessions.
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: The number of active sessions.
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: User's unique identifier.
                        screen_name:
                          type: string
                          description: User's AIM screen name or ICQ UIN.
                        online_seconds:
                          type: float
                          description: Number of seconds this user session has been online.
                        away_message:
                          type: string
                          description: User's AIM away message HTML. Empty if the user is not away.
                        idle_seconds:
                          type: float
                          description: Number of seconds this user session has been idle. 0 if not idle.
                        is_icq:
                          type: boolean
                          description: If true, indicates an ICQ user instead of an AIM user.

  /session/{screenname}:
    get:
      summary: Get active sessions for a given screen name or UIN.
      description: Retrieve a list of active sessions of a specific logged in user.
      parameters:
      - name: screenname
        in: path
        description: User's AIM screen name or ICQ UIN.
        required: true
        type: string
      responses:
        '200':
          description: Successful response containing a list of active sessions for the given screen name
          content:
            application/json:
              schema:
                type: object
                properties:
                  count:
                    type: integer
                    description: The number of active sessions.
                  sessions:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: User's unique identifier.
                        screen_name:
                          type: string
                          description: User's AIM screen name or ICQ UIN.
                        online_seconds:
                          type: float
                          description: Number of seconds this user session has been online.
                        away_message:
                          type: string
                          description: User's AIM away message HTML. Empty if the user is not away.
                        idle_seconds:
                          type: float
                          description: Number of seconds this user session has been idle. 0 if not idle.
                        is_icq:
                          type: boolean
                          description: If true, indicates an ICQ user instead of an AIM user.
        '404':
          description: User not found.

  /user/password:
    put:
      summary: Set a user's password
      description: Update the password for a user specified by their screen name or ICQ UIN.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - screen_name
                - password
              properties:
                screen_name:
                  type: string
                  description: The AIM screen name or ICQ UIN of the user whose password is to be updated.
                password:
                  type: string
                  description: The new password for the user.
      responses:
        '204':
          description: Password updated successfully.
        '400':
          description: Bad request. Invalid input data.
        '404':
          description: User not found.

  /chat/room/public:
    get:
      summary: List all public AIM chat rooms
      description: Retrieve a list of all public AIM chat rooms in exchange 5.
      responses:
        '200':
          description: Successful response containing a list of chat rooms.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the chat room.
                    create_time:
                      type: string
                      format: date-time
                      description: The timestamp when the chat room was created.
                    participants:
                      type: array
                      description: List of participants in the chat room.
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            description: User's unique identifier.
                          screen_name:
                            type: string
                            description: User's AIM screen name.

    post:
      summary: Create a new public chat room
      description: Create a new public chat room in exchange 5.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Name of the chat room.
      responses:
        '201':
          description: Chat room created successfully.
        '400':
          description: Bad request. Invalid input data.
        '409':
          description: Chat room already exists.

  /chat/room/private:
    get:
      summary: List all private AIM chat rooms
      description: Retrieve a list of all private AIM chat rooms in exchange 4.
      responses:
        '200':
          description: Successful response containing a list of chat rooms.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Name of the chat room.
                    create_time:
                      type: string
                      format: date-time
                      description: The timestamp when the chat room was created.
                    creator_id:
                      type: string
                      description: The chat room creator user ID.
                    participants:
                      type: array
                      description: List of participants in the chat room.
                      items:
                        type: object
                        properties:
                          id:
                            type: string
                            description: User's unique identifier.
                          screen_name:
                            type: string
                            description: User's AIM screen name.

  /instant-message:
    post:
      summary: Send an instant message
      description: Send an instant message from one user to another. No error is raised if the recipient does not exist or the user is offline. The sender screen name does not need to exist.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                from:
                  type: string
                  description: The AIM screen name or ICQ UIN of the sender.
                to:
                  type: string
                  description: The AIM screen name or ICQ UIN of the recipient.
                text:
                  type: string
                  description: The text content of the message.
      responses:
        '200':
          description: Message sent successfully.
        '400':
          description: Bad request. Invalid input data.