WASAPhoto/api/api.yaml

openapi: 3.0.3
info:
  title: WASAPhoto API
  description: |-
    Keep in touch with your friends by sharing photos of special moments, thanks to WASAPhoto! You can
    upload your photos directly from your PC, and they will be visible to everyone following you.
  version: "1"
paths:
  /session:
    post:
      tags: ["login"]
      summary: Logs in the user
      description: |-
        If the user does not exist, it will be created,
        and an identifier is returned.
        If the user exists, the user identifier is returned.
      operationId: doLogin
      requestBody:
        $ref: "#/components/requestBodies/userDetails"
      responses:
        '201':
          description: User log-in action successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  identifier:
                    type: string
                    example: '* imagine a Bearer token *'
  
  /session/username/{username}:
    put:
      tags: ["login"]
      summary: Updates the username
      description: Changes the username of the user with the given one
      operationId: setMyUsername
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
          description: The username to update
      responses:
        '200':
          description: Update username action successful
        '409':
          description: The chosen username is already taken

  /followers/{username}:
    post:
      tags: ["followers"]
      summary: Follows a user
      description: Starts following a user
      operationId: followUser
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
          description: The user to follow
      responses:
        '200':
          description: Follow user action successful
        '409':
          description: The user is already followed by the user
    delete:
      tags: ["followers"]
      summary: Unfollows a user
      description: Stops following a user
      operationId: unfollowUser
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
          description: The user to unfollow
      responses:
        '200':
          description: Unfollow user action successful
        '409':
          description: The user is not followed by the user

  /bans:
    post:
      tags: ["bans"]
      summary: Bans a user
      description: Bans a user //edit this please
      operationId: banUser
      security:
        - BearerAuth: []
      requestBody:
        $ref: "#/components/requestBodies/userDetails"
      responses:
        '200':
          description: Ban user action successful
        '409':
          description: The user is already banned by the user
  /bans/{username}:
    delete:
      tags: ["bans"]
      summary: Unbans a user
      description: Unbans a user //todo edit this please
      operationId: unbanUser
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
          description: The user to unfollow
      responses:
        '200':
          description: Unban user action successful
        '409':
          description: The user was not banned by the user

  /photos/{username}/{photoID}/likes:
    post:
      tags: ["photos"]
      summary: Like a photo #todo review
      description: aaa #todo review
      operationId: likePhoto
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
          description: The owner of the picture to like
        - name: photoID
          in: path
          schema:
            $ref: "#/components/schemas/photoID"
          required: true
          description: The ID of the photo to like
      responses:
        '200':
          description: Like photo action successful
        '404':
          description: The photo does not exists, or the author of the photo has banned the user
    delete:
      tags: ["photos"]
      summary: Unlike a photo #todo review
      description: aaa #todo review
      operationId: unlikePhoto
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
          description: The owner of the picture to unlike
        - name: photoID
          in: path
          schema:
            $ref: "#/components/schemas/photoID"
          required: true
          description: The ID of the photo to unlike
      responses:
        '200':
          description: Unlike photo action successful
        '404':
          description: The photo does not exists or the user was not liking the photo

  /profile/{username}: #todo maybe username not here
    get:
      tags: ["profile"]
      summary: Returns user profile
      description: todo
      operationId: getUserProfile
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
      responses:
        '200':
          description: Returns the profile details of the given user
          content:
            application/json:
              schema:
                type: object
                properties:
                  followers:
                    type: array
                    description: Array of users that the user is following
                    items:
                      $ref: "#/components/schemas/name"
                  following:
                    type: array
                    description: Array of users that are following the user
                    items:
                      $ref: "#/components/schemas/name"
                  photos:
                    $ref: "#/components/schemas/userPhotoStream"
        '404':
          description: User not found or has banned the requesting user
  /photos:
    post:
      tags: ["photos"]
      summary: Uploads a photo
      description: Uploads a photo in the gallery of the authorized user
      operationId: uploadPhoto
      security:
        - BearerAuth: []
      requestBody:
        content:
          image/jpeg:
            schema:
              format: binary
      responses:
        '201':
          description: Upload photo action successful #todo maybe get id?

  /photos/{username}/{photoID}:
    get:
      tags: ["photos"]
      summary: Download a photo
      description: Returns the requested photo
      operationId: getUserPhoto
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
        - name: photoID
          in: path
          schema:
            $ref: "#/components/schemas/photoID"
          required: true
      responses:
        '200':
          description: Returns the profile details of the given user
          content:
            image/jpeg:
              schema:
                format: binary
        '404':
          description: Photo not found
        '403':
          description: Requesting user has no permission to see the photo (banned or not following)
    delete:
      tags: ["photos"]
      summary: Deletes a photo
      description: Deletes a photo in the gallery of the authorized user
      operationId: deletePhoto
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
        - name: photoID
          in: path
          schema:
            $ref: "#/components/schemas/photoID"
          required: true
      responses:
        '200':
          description: Delete photo action successful
        '401':
          description: The user does not own the photo

  /photos/{username}/{photoID}/comments:
    post:
      tags: ["comments"]
      summary: Comments a photo #todo review
      description: aaa #todo review
      operationId: commentPhoto
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
        - name: photoID
          in: path
          schema:
            $ref: "#/components/schemas/photoID"
          required: true
      requestBody:
        description: User details
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  example: "What a lovely picture! 😊"
      responses:
        '200':
          description: Comment photo action successful
        '404':
          description: The photo does not exists, or the author of the photo has banned the user

  /photos/{username}/{photoID}/comments/{commentID}:
    delete:
      tags: ["comments"]
      summary: Deletes a comment
      description: Deletes a photo in the gallery of the authorized user
      operationId: deleteComment
      security:
        - BearerAuth: []
      parameters:
        - name: username
          in: path
          schema:
            $ref: "#/components/schemas/name"
          required: true
        - name: photoID
          in: path
          schema:
            $ref: "#/components/schemas/photoID"
          required: true
        - name: commentID
          in: path
          schema:
            $ref: "#/components/schemas/commentID"
          required: true
      responses:
        '200':
          description: Delete photo action successful
          
  /stream: #todo parametri per lazy loading
    get:
      tags: ["stream"]
      summary: Returns user stream
      description: todo
      operationId: getMyStream
      security:
        - BearerAuth: [] #todo maybe not needed
      parameters:
          - name: limit
            in: query
            schema:
              type: integer
              default: 25
            description: The number of elements to show
            required: false
          - name: startIndex
            in: query
            schema:
              type: integer
              default: 0
            description: The starting offset
            required: false
      responses:
        '200':
          description: Returns the profile details of the given user
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/photoStream"


components:

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer

  schemas:
    name:
      type: string
      example: Maria
      pattern: 'ˆ.*?$'
      minLength: 3
      maxLength: 16
    photoID:
      type: integer
      description: The ID of the photo
      example: 1527
    commentID:
      type: integer
      description: The ID of the comment
      example: 3
    uploadTime:
      type: string
      format: date-time
      description: Photo upload time and date
    likes:
      type: integer
      example: 90
      description: Number of likes
    userPhotoStream:
      type: array
      items:
        type: object
        properties:
          photoID:
            $ref: "#/components/schemas/photoID"
          uploadTime:
            $ref: "#/components/schemas/uploadTime"
          likes:
            $ref: "#/components/schemas/likes"
    photoStream:
      type: array
      items:
        type: object
        properties:
          username:
            $ref: "#/components/schemas/name"
          photoID:
            $ref: "#/components/schemas/photoID"
          uploadTime:
            $ref: "#/components/schemas/uploadTime"
          likes:
            $ref: "#/components/schemas/likes"

  requestBodies:
    userDetails:
      description: User details
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                $ref: "#/components/schemas/name"
      required: true

    photoDetails:
      description: Photo details
      content:
        application/json:
          schema:
            type: object
            properties:
              username:
                $ref: "#/components/schemas/name"
              photo:
                $ref: "#/components/schemas/photoID"
      required: true