openapi: 3.0.0
servers:
  - url: 'https://medreg.lysator.liu.se'

info:
  title: Lysator Medreg
  description: .
  contact: 
    email: busk@lysator.liu.se
  version: 0.1.0

security:
  - OpenId: []

paths:
  /api/Admin/MemberByNumber/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags: [Admin]
      operationId: memberByNumber
      summary: >-
        Get member by arbitrary membership number
      responses:
        '200':
          description: The member in question
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/MemberEntry'
        '404':
          description: No member with that number exists

  /api/admin/MembersByLoginOrName/{name}:
    parameters:
      - name: name
        schema:
          type: string
        description: >-
          Either a persons regular name, or their Lysator login.
          Can be a partail match.
        required: true
        in: path
    get:
      tags: [Admin]
      operationId: membersByLoginOrName
      summary: >-
        Find all members which name matching the query
      responses:
        '200':
          description: A list of matches, may be empty
          content:
            'application/json':
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MemberEntry'

  /api/admin/MemberByPnr:
    post:
      tags: [Admin]
      operationId: memberByPnr
      summary: >-
        Fetch a user by swedish personal identification number.

        Number in POST body probably to not leak the numbers.
        TODO fråga busk
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              required: [pnr]
              properties:
                pnr:
                  $ref: '#/components/schemas/PersonalIdNumber'
      responses:
        '200':
          description: The member with that personal identification number
          content:
            'application/json':
              schema:
                $ref: '#/components/schemas/MemberEntry'
        '404':
          description: No member with that personal id number exists.

  /api/admin/RegisterPayment:
    post:
      tags: [Admin]
      operationId: registerPayment
      summary: >-
        Register a payment from a member.
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              required:
                - Number
                - Years
              properties:
                Number:
                  $ref: '#/components/schemas/UserId'
                Years:
                  type: integer
                  description: >-
                    How many years should be added to the users
                    membership.
      responses:
        '200':
          description: >-
            Payment registered successfully.
          content:
            'application/json':
              schema:
                type: object
                required: [expdate]
                properties:
                  expdate:
                    type: string
                    format: date
                    description: >-
                      New end date for the persons membership
        '404':
          description: >-
            No member with that id exists.

  /api/admin/UpdateStatus/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags: [Admin]
      operationId: updateStatus
      summary: >-
        Update the current status of a membership
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              required: [Status]
              properties:
                Status:
                  $ref: '#/components/schemas/MembershipStatus'
      responses:
        '204':
          description: Successfully updated
        # TODO test this status. The server throws an
        # ArgumentException, which might result in a 500-series code.
        '400':
          description: An invalid status was given
        '404':
          description: No user with that id

  /api/admin/DeleteMember/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    delete:
      tags: [Admin]
      operationId: deleteMember
      summary: >-
        Delete the given member
      responses:
        '204':
          description: Member successfully deleted
        '400':
          description: >-
            Either the member doesn't exist, alternatively, it isn't
            marked passive.

            TODO shouldn't this be split into 404 and 412?

  /api/admin/UpdateLogin/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags: [Admin]
      operationId: updateLogin
      summary: >-
        Change the login name for a user.
      requestBody:
        content:
          'application/json':
            schema:
              type: object
              required: [NewLogin]
              properties:
                NewLogin:
                  type: string
      responses:
        # Probably. The server returns `ActionResult<Member>(member)`
        # TODO
        # '200': {}
        '400':
          # This maybe doesn't return correctly. Server throws
          # ArgumentException
          description: >-
            Either the login is empty, no member with that id
            exists, or another member with that name already exists.

            TODO thish ought to be split into 400, 404, and 409/412.

  # TODO check this more.
  # Seems like it takes a dictionary, containing fields to change
  # And possibly always the key "changetext"
  /api/admin/Update/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    post:
      tags: [Admin]
      operationId: update
      summary: >-
        Updates some form of something
      requestBody:
        content:
          'application/json':
            schema:
              type: object


  /api/admin/history/{id}:
    parameters:
      - $ref: '#/components/parameters/id'
    get:
      tags: [Admin]
      operationId: getHistory
      summary: >-
        Get history of changes for a given user.
      responses:
        '200':
          description: The users history
          content:
            'application/json':
              schema:
                type: array
                items: 
                  $ref: '#/components/schemas/HistoryEntry'

  /api/misc/authtest:
    get:
      tags: [misc]
      operationId: authtest
      summary: >-
        Check if successfully authorized.
      responses:
        '200':
          description: You are authorized
          content:
            'text/plain':
              schema:
                type: string
                example: You are logged in as hugo
        '401':
          description: You are not authenticated

  /api/misc/lastpayment:
    get:
      tags: [misc]
      operationId: lastpayment
      summary: >-
        Get the last registered payment in the system
      responses:
        '200':
          description: .
          content:
            'text/plain':
              schema:
                type: string

# TODO
# /api/maillist/memberlist:
#   tags: [maillist]


  # TODO
# /api/self/info:
#   get:
#     tags: [self]
#     operationId: selfInfo
#   summary: Return user visible information about the self.

components:

  securitySchemes:
    # bearerAuth:
    #   type: http
    #   scheme: bearer
    OpenId:
      type: openIdConnect
      openIdConnectUrl: https://login.lysator.liu.se/auth/realms/Lysator/.well-known/openid-configuration
      # authorization: Bearer ${token}

  parameters:
    id:
      name: id
      in: path
      required: true
      description: >-
        User to operate on
      schema:
        $ref: '#/components/schemas/UserId'

  schemas:

    PersonalIdNumber:
      type: string
      pattern: '\d{10}-\d{4}'
      description: >-
        Swedish identification number.
      example: 19890201-3286

    EmptyString:
      type: string
      pattern: '^$'
      description: >-
        Most fields are always present in responses, but default to an
        empty string if the value isn't available.
      example: ''

    LiuId:
      type: string
      pattern: '^\w{4,5}\d{2,3}$'
      description: >-
        LiU-id.

        TODO what is actually the format of LiU-id:n?
      example: jambo007

    UserId:
      type: integer
      format: int32
      description: >-
        Arbitrary Lysator membership number

    MembershipStatus:
      type: string
      enum:
        - active
        - passive
        - expelled
      description: >-
        Current status of the user.

    HistoryEntry:
      type: object
      required:
        - hdatetime
        - hlogin
        - hnumber
        - hprg
        - hsecret
        - htext
        - id
      properties:
        hdatetime: 
          type: string
          format: date-time
          description: >-
            Time of the entry.
            
            NOTE Even though the Open-API spec requires a timezone
            (e.g. 'Z') its not present here. Europe/Stockholm should
            be assumed.
        hlogin:
          type: string
          description: >-
            Name of the account which caused this entry.
            The system itself registers as 'medreg', otherwise a
            Lysator account name will be present.
        hnumber:
          $ref: '#/components/schemas/UserId'
            # - description:  Member which this entry is about
        hprg:
          type: string
          description: >-
            The client program which was used to generate this entry.
        hsecret:
          type: integer
          description: >-
            ???, but seems to always be 0.
        htext:
          type: string
          description: >-
            Plain text description of what the change entailed.
        id:
          type: integer
          description: >-
            (Probably) database key.


    MemberEntry:
      type: object
      required:
        - address
        - admin
        - admitted
        - birth
        - checkedpnr
        - email
        - expdate
        - haveAhcard
        - integrastatus
        - liuid
        - login
        - lysatorCardNumber
        - name
        - number
        - password
        - phone
        - pnr
        - remark
        - reminded
        - status
        - token
        - tokenexp
        - type
      properties:
        address: 
          type: string
          description: >-
            Street address for the user. Probably multiple lines.
            Sepparated by \r\n
          example: |-
            Gatuvägen 100
            123 45  Linköping
        admin:
            type: string
            enum:
              - admin
              - normal
            description: |
              TODO what is this?
        admitted:
          type: string
          format: date
          description: When the person first became a member.
        birth:
          type: string
          format: date
          description: Birthdate for the member.
        checkedpnr:
          type: string
          enum: ['yes']
          description: >-
            Has the members Swedish personal identification number
            been checked agains a photo id card?

            TODO what are valid values?
        email:
          type: string
          format: email
          description: Primary email for the user
        expdate:
          type: string
          format: date
          description: Date when the persons membership expires
        haveAhcard:
          type: string
          enum: ['yes']
          description: >-
            Does this person possess an "Akademiska Hus" card?

            TODO valid values?
        integrastatus:
          type: string
          enum:
            - investigating
            - active
          description: >-
            Status for their AH card. Used when peoples permissons
            aren't as expected.

            TODO valid values?
        liuid:
          oneOf:
            - $ref: '#/components/schemas/LiuId'
            - $ref: '#/components/schemas/EmptyString'
        login:
          type: string
          description: Primary Lysator username.
        lysatorCardNumber:
          type: string
          description: ???
        name:
          type: string
          description: Real-World name of the user.
        number:
          $ref: '#/components/schemas/UserId'
        password:
          type: string
          format: password
          description: ???
        phone:
          type: string
          description: Primary phone number of the user
        pnr:
          oneOf:
            - $ref: '#/components/schemas/PersonalIdNumber'
            - $ref: '#/components/schemas/EmptyString'
        remark:
          type: string
          description: Free text field for extra notes.
        reminded:
          type: string
          format: date
          description: >-
            Date when they last received an email reminder about
            paying their membership fees.
        status:
          $ref: '#/components/schemas/MembershipStatus'
        token:
          type: string
          description: ???
        tokenexp:
          type: integer
          description: ???
        type:
          type: string
          enum:
            - normal
            - inspector
            # - hedesmedlem
          description: Type of membership