api-contracts.yml

openapi: 3.0.3
info:
  title: Skill tree API contracts
  version: 1.0.11

tags:
  - name: skills
    description: Everything about user skills
  - name: endorsements
    description: Everything about endorsements made

paths:
  /skills:
    get:
      tags:
        - skills
      summary: Get all the skills
      description: It can be used in auto complete of search feature.
      operationId: getAllSkills
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/skills'

        '404':
          description: Skills not found
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureAllSkills'


        '503':  
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureServiceUnavailable'

  /skills/{userId}:
    get:
      tags:
        - skills
      parameters:
        - in: path
          name: userId
          required: true
          schema:
            type: string

      summary: Get all the skills of the user
      description: Get all the skills of the user
      operationId: getSkillForUser
      responses:
        '200':
          description: Successful operation
          content: 
            application/json:
              schema:
                type: array
                items:
                 $ref: '#/components/schemas/skills'

        '404':
          description: No skills associated with the user.
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureNoSkillsForUser'

        '400':
          description: Incorrect userId passed.
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureInvalidParameter'

        '503':  
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureServiceUnavailable'



  /skills/name/{name}:
    get:
      tags: 
        - skills
      parameters:
        - in: path
          name: name
          required: true
          schema: 
            type: string

      summary: Get all the users for the given skill
      description: Get all the users for the given skill
      operationId: getUsersForSkill
      responses:
        '200': 
          description: Successful operation
          content:
            application/json:
              schema:
                type: object 
                $ref: '#/components/schemas/ApiResponseForSkillName'
        '404':
          description: No user found for the skill searched
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureNoUsersForSkillName'

        '400':
          description: Incorrect skillName passed.
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureInvalidParameter'

        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureServiceUnavailable'


  /endorsements:
    get:
      tags:
        - endorsements
      summary: Fetch all endorsements / query based on skillID and userID
      description: Fetch all endorsements / query based on skillID and userID
      operationId: getEndorsements
      parameters:
        - name: userID
          in: query
          description: The ID of the user
          required: false
          schema:
            type: string
            example: f47ac10b-58cc-4372-a567-0e02b2c3d479
        - name: skillID
          in: query
          description: The ID of the skill 
          required: false
          schema:
            type: string
            example: 550e8400-e29b-41d4-a716-446655440000
      
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/DummyEndorsementResponse'

        '204':
          description: endorsement not found

        '400':
          description: Invalid parameter(s)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseFailureInvalidParameter'
              examples:
                invalidParameterUUID:
                  value:
                    code: BAD_REQUEST
                    message: Invalid parameter(s) provided

        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseFailureServiceUnavailable'
    post:
      tags:
        - endorsements
      summary: Create an endorsement for a skill
      description: Create an endorsement for a skill
      operationId: createEndorsement
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/endorsementRequest'

      responses:
        '200':
          description: Created endorsement sucessfully
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/endorsementResponse'

        '503':
          description: Endorsement creation failed
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureServiceUnavailable'



  /endorsements/{id}?status={EndorsementStatus}:
    patch:
      tags:
        - endorsements
      parameters:
        - name: id
          schema:
            type: string
            format: UUID
          in: path
          description: EndorsementId which has to be modified
          required: true
        - name: status
          schema:
            type: string,
            format: EndorsementStatus,
          in: query       
          description: New endorsement status which has to be updated
          required: true   
      summary: Update endorsement status given endorsementId
      description: Update endorsement status given endorsement id, **this can be only used by Super User for now**
      operationId: updateEndorsementStatusGivenId

      responses:
        '200':
          description: update operation successful
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/UpdateEndorsementResponse'

        '400':
          description: Invalid endorsement Id value
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureInvalidParameter'

        '400':
          description: Invalid endorsement status
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureInvalidParameter'
        
        '409':
          description: Updating the status of an endorsement that has been accepted/rejected
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureEndorsementUpdateResponse'

        '403':
          description: Unauthorized access, user is not a super user
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureUnauthorized'

        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureServiceUnavailable'

    get:
      tags:
        - endorsements
      parameters:
        - name: endorsementId
          schema: 
            type: string
          in: path
          description: EndorsementId whose details are to be fetched
          required: true
      description: Fetch details for a particular endorsement
      summary: Fetch details for a particular endorsement
      operationId: getEndorsementById
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/endorsementResponse'

        '404': 
          description: Endorsement not found
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureNoEndorsementFound'

        '400':
          description: Invalid endorsementId passed
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureInvalidParameter'

        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                type: object
                $ref: '#/components/schemas/ApiResponseFailureServiceUnavailable'


components:
  schemas:
    skills:
      type: object
      properties:
        id:
          type: string
          example: skill-1
        name:
          type: string
          example: Java
        type:
          type: string
          example: atomic / derived
        description:
          type: string

    endorsementUpdate:
      type: object
      properties:
        status:
          type: string
          enum: 
            - PENDING
            - APPROVED
            - REJECTED
          default: APPROVED
    endorsementResponse:
      type: object
      properties:
        endorseeId:
          type: string
          example: user-1
        skillName:  
          type: string
          example: Java
        status: 
          type: string
          enum:
            - PENDING
            - APPROVED
            - REJECTED
          default: APPROVED
        endorsementType:
          type: string
          enum: 
            - POSITIVE
            - NEGATIVE
          default: POSITIVE
        endorsersList:
          type: array
          items:  
            $ref: '#/components/schemas/endorserObject'
    endorserObject:
      type: object
      properties:
        endorserId:
          type: string
          example: user-2
        description:
          type: string
          minimum: 1
          maximum: 256
        userType:
          type: string
          enum:
            - NORMAL_USER
            - SUPER_USER
            - MAVEN
    endorsementRequest:
      required:
        - skillName
        - endorserUserId
        - endorseeUserId
        - description
        - behaviour

      type: object
      properties:
        skillName:
          type: string
          example: Java
        endorserUserId:
          type: string
          example: user-1
        endorseeUserId:
          type: string
          example: user-2
        behaviour:
          type: string
          default: POSITIVE
          enum: 
            - POSITIVE
            - NEGATIVE

        description:
          type: string
          minimum: 1
          maximum: 256

    skillUsersResponse:
      type: object
      properties:
        skillName:  
          type: string
          example: Java
        userName: 
          type: string
          example: John doe

    DummyEndorsementResponse:
      type: object
      properties:
        content:
          type: array
          items:
            $ref: '#/components/schemas/DummyEndorsement'
        pageable:
          $ref: '#/components/schemas/Pageable'
        last:
          type: boolean
        totalElements:
          type: integer
        totalPages:
          type: integer
        first:
          type: boolean
        size:
          type: integer
        number:
          type: integer
        sort:
          $ref: '#/components/schemas/Sort'
        numberOfElements:
          type: integer
        empty:
          type: boolean

    DummyEndorsement:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: ["PENDING", "APPROVED"]
        user_id:
          type: string
          format: uuid
        skill_id:
          type: string
          format: uuid
        created_at:
          type: string
          format: date-time
        created_by:
          type: string
          format: uuid
        updated_at:
          type: string
          format: date-time
        updated_by:
          type: string
          format: uuid

    Pageable:
      type: object
      properties:
        sort:
          $ref: '#/components/schemas/Sort'
        offset:
          type: integer
        pageSize:
          type: integer
        pageNumber:
          type: integer
        paged:
          type: boolean
        unpaged:
          type: boolean

    Sort:
      type: object
      properties:
        empty:
          type: boolean
        sorted:
          type: boolean
        unsorted:
          type: boolean

          
    ApiResponseFailureAllSkills:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 404
        message:
          type: string  
          example: Skills not found
    ApiResponseFailureNoSkillsForUser:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 404
        message:
          type: string  
          example: No skills associated with the user.
    ApiResponseFailureNoUsersForSkillName:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 404
        message:
          type: string  
          example: No user found for the skill searched
    ApiResponseFailureNoEndorsementFound:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 404
        message:
          type: string  
          example: Endorsement not found

    ApiResponseFailureServiceUnavailable:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 503
        message:
          type: string  
          example: Service unavailable
    ApiResponseFailureInvalidParameter:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 400
        message:
          type: string  
          example: Invalid paramter passed

    ApiResponseForSkillName:
      type: array
      items:  
        $ref: '#/components/schemas/skillUsersResponse'

    UpdateEndorsementResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 200
        message:
          type: string  
          example: Successfully updated endorsement status

    ApiResponseFailureUnauthorized:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 403
        message:
          type: string  
          example: Unauthorized, Access is only available to super users
    
    ApiResponseFailureEndorsementUpdateResponse:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: 409
        message:
          type: string  
          example: Endorsement is already updated, Cannot modify status