openapi: 3.0.0

info:
  title: Ringfinger API
  version: 1.0.0
  description: The restfull API of the jabber fingerprint keyring.

tags:
  - name: User
    description: A user that can login, store fingerprints and share them with other users.
  - name: Fingerprint
    description: The jabber fingerprint owned by a user.
  - name: Sharing
    description: The sharing of all fingerprints of a user with another user.

paths:
  '/api/v1/user/{userId}':
    get:
      tags:
        - User
      summary: Returns the user attributes
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        200:
          description: Returns the user data for the given id.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
                  result:
                    type: object
                    description: Contains the user data.
                    properties:
                      userId:
                        $ref: '#/components/schemas/UserId'
                      usernamme:
                        $ref: '#/components/schemas/Username'
                      jabberAddress:
                        $ref: '#/components/schemas/JabberAddress'
                      isAdmin:
                        type: boolean
                        description: Returns if the user has admin permissions.
                        example: true
                      fingerprintIds:
                        type: array
                        items:
                          type: integer
                        description: A list of all fingerprint ids of the user.
                        example: [25, 42, 88]
                        default: []
        default:
          $ref: '#/components/responses/Error'
    put:
      tags:
        - User
      summary: Changes user attributes
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        required: true
        description: Contains the json with the user attributes that have to be changed.
        content:
          application/json:
            schema:
              properties:
                username:
                  $ref: '#/components/schemas/Username'
                password:
                  $ref: '#/components/schemas/Password'
                email:
                  $ref: '#/components/schemas/EmailAddress'
                jabberAddress:
                  $ref: '#/components/schemas/JabberAddress'
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - User
      summary: Deletes a user
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/user/{userId}/sharings':
    get:
      tags:
        - User
      summary: A list of all sharings with other users.
      responses:
        200:
          description: Returns the success state and a list with all sharings of the user.
          content:
            application/json:
              schema:
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
                  sharings:
                    type: array
                    items:
                      type: object
                    example:
                      - sharingId: 8
                        userId: 25
                        userSharingId: 42
                      - sharingId: 9
                        userId: 25
                        userSharingId:
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/user/{userId}/fingerprints':
    get:
      tags:
        - User
      summary: A list containing all fingerprints of the user
      responses:
        200:
          description: Returns the success state and a list with all fingerprints of the user.
          content:
            application/json:
              schema:
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
                  fingerprints:
                    type: array
                    items:
                      type: object
                    example:
                      - fingerprintId: 8
                        fingerprint: '5BDF1668E59F2184582591699F55D9158DEF400A48772887A8F61531ED36B2A'
                        userId: 25
                      - fingerprintId: 42
                        fingerprint: '6FF8842B6D17F5C2098A3DD8AB55D9158DEF400A48772887A8F61531ED36B2A'
                        userId: 25
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/user/{userId}/email':
    get:
      tags:
        - User
      parameters:
        - $ref: '#/components/parameters/UserId'
      summary: Returns the user's email address
      responses:
        200:
          description: Contains a JSON object with the success state and the email address.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
                  email:
                    $ref: '#/components/schemas/EmailAddress'
        default:
          $ref: '#/components/responses/Error'
    put:
      tags:
        - User
      summary: Changes the user's email address
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  $ref: '#/components/schemas/EmailAddress'
              allOf:
                - required:
                  - email
      responses:
        200:
          description: Returns the success state for the change request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/user/{userId}/password':
    put:
      tags:
        - User
      summary: Changes the password of the user
      parameters:
        - $ref: '#/components/parameters/UserId'
      requestBody:
        description: The password inside a json object.
        content:
          application/json:
            schema:
              type: object
              properties:
                password:
                  type: string
                  description: The new password.
                  example: '12345'
              allOf:
                - required:
                  - password
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/user/{userId}/admin':
    post:
      tags:
        - User
      summary: Gives the user admin permissions
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - User
      summary: Removes the user's admin permissions
      parameters:
        - $ref: '#/components/parameters/UserId'
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/user':
    post:
      tags:
        - User
      summary: Creates a new user
      requestBody:
        required: true
        description: 'The attributes for the user to be created.'
        content:
          application/json:
            schema:
              properties:
                username:
                  $ref: '#/components/schemas/Username'
                password:
                  $ref: '#/components/schemas/Password'
                email:
                  $ref: '#/components/schemas/EmailAddress'
                jabberAddress:
                  $ref: '#/components/schemas/JabberAddress'
              allOf:
                - required:
                    - username
                    - password
                    - email
                    - jabberAddress
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/user/session':
    post:
      tags:
        - User
      summary: Creates a user session (login)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                username:
                  $ref: '#/components/schemas/Username'
                password:
                  $ref: '#/components/schemas/Password'
              allOf:
                - required:
                    - username
                    - password
      responses:
        200:
          description: Returns the success state and the user id for the created session.
          content:
            application/json:
              schema:
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
                  userId:
                    $ref: '#/components/schemas/UserId'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - User
      summary: Deletes a user session (logout)
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/fingerprint/{fingerprintId}/qr':
    get:
      tags:
        - Fingerprint
      summary: Returns the fingerprint's QR code
      parameters:
        - $ref: '#/components/parameters/FingerprintId'
      responses:
        200:
          description: The QR code as SVG image
          content:
            application/svg+xml:
              schema:
                type: string
                description: The xml of the SVG image.
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/fingerprint/{fingerprintId}':
    get:
      tags:
        - Fingerprint
      summary: Returns the attributes of the fingerprint
      parameters:
        - $ref: '#/components/parameters/FingerprintId'
      responses:
        200:
          description: Returns the fingerprint for the given fingerprint id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FingerprintData'
        default:
          $ref: '#/components/responses/Error'
    put:
      tags:
        - Fingerprint
      summary: Changes the fingerprint
      parameters:
        - $ref: '#/components/parameters/FingerprintId'
      requestBody:
        content:
          application/json:
            schema:
              properties:
                fingerprint:
                  $ref: '#/components/schemas/Fingerprint'
              required:
                - fingerprint
      responses:
        200:
          description: Returns the success state.
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    description: 'Returns the success state of the fingerprint change.'
                    example: true
                  message:
                    type: string
                    description: 'Returns if no changes have been found inside the request body.'
                    example: 'Fingerprint did not differ from the stored. Nothing changed.'
                required:
                  - success
        default:
          $ref: '#/components/responses/Error'

    delete:
      tags:
        - Fingerprint
      summary: Removes the fingerprint
      parameters:
        - $ref: '#/components/parameters/FingerprintId'
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/fingerprint':
    post:
      tags:
        - Fingerprint
      summary: Creates a new fingerprint
      requestBody:
        content:
          application/json:
            schema:
              description: The parameters for the new fingerprint to be created.
              properties:
                fingerprint:
                  $ref: '#/components/schemas/Fingerprint'
                userId:
                  $ref: '#/components/schemas/UserId'
              required:
                - fingerprint
                - userId

      responses:
        200:
          description: Returns the confirmation and the id for the newly created fingerprint.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Returns the success status.
                    example: true
                  fingerprintId:
                    type: integer
                    description: The id for the newly created fingerprint.
                    example: 42
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/sharing/{sharingId}':
    get:
      tags:
        - Sharing
      summary: Returns the sharing attributes
      parameters:
        - $ref: '#/components/parameters/SharingId'
      responses:
        200:
          description: The JSON result for the sharing.
          content:
            application/json:
              schema:
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
                  result:
                    type: object
                    properties:
                      sharingId:
                        $ref: '#/components/schemas/SharingId'
                      userId:
                        type: integer
                        description: The id of the user that shares his fingerprints.
                        example: 42
                      userSharedId:
                        $ref: '#/components/schemas/SharingUserId'
        default:
          $ref: '#/components/responses/Error'
    delete:
      tags:
        - Sharing
      summary: Removes the specified sharing
      parameters:
        - $ref: '#/components/parameters/SharingId'
      responses:
        200:
          $ref: '#/components/responses/Success'
        default:
          $ref: '#/components/responses/Error'

  '/api/v1/sharing':
    post:
      tags:
        - Sharing
      summary: Creates a new sharing
      requestBody:
        description: Contains the attributes for the sharing to be created.
        content:
          application/json:
            schema:
              type: object
              properties:
                userId:
                  type: integer
                  description: The id of the user that shares his fingerprints.
                  example: 42
                userSharedId:
                  $ref: '#/components/schemas/SharingUserId'
              allOf:
                - required:
                    - userId
                    - userSharedId

      responses:
        200:
          description: Returns the success flag and the id for the newly created sharing.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    $ref: '#/components/schemas/Success'
                  sharingId:
                    $ref: '#/components/schemas/SharingId'
        default:
          $ref: '#/components/responses/Error'

components:
  parameters:
    FingerprintId:
      name: fingerprintId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/FingerprintId'

    SharingId:
      name: sharingId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/SharingId'

    UserId:
      name: userId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UserId'

  responses:
    Success:
      description: Returns that the request could be handled successfully.
      content:
        application/json:
          schema:
            properties:
              success:
                $ref: '#/components/schemas/Success'

    Error:
      description: Returns a JSON object that describes the error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'

  schemas:
    Error:
      type: object
      properties:
        success:
          type: boolean
          description: Returns that the request couldn't be handled.
          example: false
        message:
          type: string
          description: Description of the error that occured.
          example: Something extremely terrible happened!

    Success:
      type: boolean
      description: Returns if the request could be handled.
      example: true

    UserId:
      type: integer
      description: The id of the user in question.
      example: 42

    Username:
      type: string
      description: The login name for the given user.
      example: Kevin42

    Password:
      type: string
      description: The password for the user login.
      example: '12345'

    JabberAddress:
      type: string
      description: The address of the jabber account.
      example: donalt@jabber.de

    EmailAddress:
      type: string
      description: The registered email address for the user.
      example: kevin42@gmail.com

    FingerprintId:
      type: integer
      description: The id that identifies the fingerprint.
      example: 42
      readOnly: true

    Fingerprint:
      type: string
      description: The jabber fingerprint
      example: '5BDF1668E59F2184582591699F55D9158DEF400A48772887A8F61531ED36B2A'

    FingerprintData:
      type: object
      properties:
        fingerprintId:
          $ref: '#/components/schemas/FingerprintId'
        fingerprint:
          $ref: '#/components/schemas/Fingerprint'
        userId:
          type: integer
          description: The id of the user that owns this fingerprint.
          example: 25

    SharingId:
      type: integer
      description: The id for the sharing.
      example: 42
      readOnly: true

    SharingUserId:
      type: integer
      description: The id of the user who is allowed to display the fingerprints.
      example: 25