catroweb.yaml

openapi: 3.0.3
info:
  title: "Catroweb API"
  description: "API for the Catrobat Share Platform"
  version: "v1.6.0"
  termsOfService: "https://share.catrob.at/pocketcode/termsOfUse"
  contact:
    name: "Catrobat"
    url: "https://share.catrob.at"
    email: "webmaster@catrobat.org"

servers:
  - url: 'https://share.catrob.at/api'
    description: "Main production server"
  - url: 'https://web-test.catrob.at/api'
    description: "Our test server (might be unstable)"
  - url: 'http://localhost/api'
    description: "Local test server (postman help)"

tags:
  - name: "Authentication"
    description: "
        * To have **full access** to all our features it is necessary to be **authenticate**d.\n
        * Our authentication system utilizes **JWT** (https://jwt.io/introduction).\n
        * The bearer token you retrieve on login must be send in the **Authorization Header** of all following requests.\n
        - **Example**: `curl -H \"Authorization: Bearer sagu4235afsyvyvdgsdqaWER22\" /route` 
      "

  - name: "User"
    description: "Everything related to users; from registration to managing their data."

  - name: "Projects"
    description: "Everything related to projects"

  - name: "Media Library"
    description: "Everything related to the media library"

  - name: "Utility"
    description: "Utility functionality"

  - name: "Notifications"
    description: "Everything related for notifications"

  - name: "Search"
    description: "Everything related to searching"

  - name: "Studio"
    description: "Create, join and update studios"

paths:

  ##############################################
  # Authentication
  ###
  /authentication:
    get:
      security:
        - BearerAuth: [ ]
      tags:
        - "Authentication"
      summary: "Check JWT token validity"
      description: "Checks if a token is valid or expired."
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

    post:
      security:
        - BearerAuth: [ ]
      tags:
        - "Authentication"
      summary: "Login - create a new JWT token"
      description: "Returns an JWT token which provides authorization for a limited time"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

    delete:
      security:
        - BearerAuth: [ ]
      tags:
        - "Authentication"
      summary: "Expires refresh token"
      description: "Sets refresh token to expired"
      parameters:
        - $ref: '#/components/parameters/RefreshToken'
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidRefreshToken'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

  /authentication/refresh:
    post:
      security:
        - BearerAuth: [ ]
      tags:
        - "Authentication"
      summary: 'Refresh token'
      description: "Returns a new JWT token with help of the refresh token"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshRequest'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidRefreshToken'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

  /authentication/upgrade:
    post:
      tags:
        - "Authentication"
      summary: 'Upgrade a deprecated token to JWT'
      description: "Returns a new JWT token with help of a deprecated upload_token. This allows users to stay signed in apps during the transition to the new API."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpgradeTokenRequest'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidUploadToken'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'

  /authentication/oauth:
    post:
      tags:
        - "Authentication"
      summary: "OAuth Login"
      description: "Returns an JWT token which provides authorization"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OAuthLoginRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidIdToken'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        422:
          description: "Unprocessable Entity"

  ##############################################
  # Utility
  ###
  /health:
    get:
      tags:
        - "Utility"
      summary: "Health Check"
      responses:
        '204':
          description: "System is alive and healthy!"

  /survey/{lang_code}:
    get:
      parameters:
        - in: path
          name: lang_code
          schema:
            type: string
            example: "de"
          required: true
          description: "2 letter Language-Code is based on ISO693-1 (e.g. German = de, English = en, Russian = ru)"
        - $ref: '#/components/parameters/Flavor'
        - $ref: '#/components/parameters/Platform'
      tags:
        - Utility
      summary: "Get survey link for given language code."
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  ##############################################
  # User
  ###
  /user:

    get:
      security:
        - BearerAuth: [ ]
      tags:
        - "User"
      summary: "Get your private user data"
      description:
        "
          Get your private user data. Additionally to the public user data,
          this responses contains all your private data like settings.
        "
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtendedUserDataResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '406':
          $ref: '#/components/responses/NotAcceptable'

    post:
      parameters:
        - $ref: '#/components/parameters/Locale'
      tags:
        - User
      summary: "Register"
      description:
        "
          Register a user. For pre-validation use the dry-run option.
          Using Dry run the request is validated but no object is created on the server.
        "
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
      responses:
        201:
          description: "User successfully registered"
          headers:
            Location:
              schema:
                type: string
                example: "https://share.catrob.at/app/user/3ef85528-5f08-11ea-a2ae-000c292a0f49"
              description: Resource location on server
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTResponse'
        204:
          description: 'Dry-run successful (No Validation Error)'
        400:
          $ref: '#/components/responses/BadRequest'
        406:
          $ref: '#/components/responses/NotAcceptable'
        415:
          $ref: '#/components/responses/UnsupportedMediaType'
        422:
          description: "Unprocessable Entity (Specific error messages will be translated to the locale)"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterErrorResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'

    put:
      parameters:
        - $ref: '#/components/parameters/Locale'
      security:
        - BearerAuth: [ ]
      tags:
        - "User"
      summary: "Update User"
      description:
        "
          Update your user account. All attributes are optional.
          For example you can update only the username.
          Or you can update multiple attributes at once. E.g. username + email.
        "
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateUserRequest'
      responses:
        '204':
          description: "User successfully updated"
          # Content hack necessary else OpenAPI-generator will ignore content for error responses (hopefully fixed sometime)
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '422':
          description: "Unprocessable Entity. (Specific error messages will be translated to the locale)"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateUserErrorResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'

    delete:
      security:
        - BearerAuth: [ ]
      tags:
        - "User"
      summary: "Delete user account"
      description: "Delete your user account. But be warned, there is no way to restore the user data!"
      responses:
        '204':
          description: User successfully deleted.
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  /user/{id}:
    get:
      tags:
        - "User"
      summary: "Get public user data"
      description: "Get all the public data of a user"
      parameters:
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BasicUserDataResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  /user/reset-password:
    post:
      tags:
        - "User"
      summary: "Request email to reset password"
      description:
        "
          If an account with the provided email exists, an email to reset the password will be sent to the user.
          The email contains a link to reset the password. Note: This link is only valid for a limited amount of time.
        "
      parameters:
        - $ref: '#/components/parameters/Locale'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPasswordRequest'
      responses:
        '204':
          description: "If an account with this email exists, an email to reset the password will be send to the user"
          # Content hack necessary else OpenAPI-generator will ignore content for error responses (hopefully fixed sometime)
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          description: "Unprocessable Entity. (Specific error messages will be translated to the locale)"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResetPasswordErrorResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'


  /users/search:
    get:
      tags:
        - "User"
      summary: "Search for users"
      description: "Search for users associated by keywords."
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersDataResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  /users:
    get:
      tags:
        - "User"
      summary: "Get users"
      description: "Get all users with their corresponding data"
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsersDataResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  ################################################
  # Projects
  #
  /projects:
    parameters:
      - $ref: '#/components/parameters/Locale'

    get:
      tags:
        - "Projects"
      summary: "Get projects"
      parameters:
        - $ref: '#/components/parameters/ProjectType'
        - $ref: '#/components/parameters/MaxVersion'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

    post:
      security:
        - BearerAuth: [ ]
      tags:
        - "Projects"
      summary: "Upload a catrobat project"
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ProjectUploadRequest'
      responses:
        '201':
          description: "Project successfully uploaded"
          headers:
            Location:
              schema:
                type: string
                example: "https://share.catrob.at/app/project/63768cf1-5f07-11ea-a2ae-000c292a0f49"
              description: "Resource location on server"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '422':
          description: "Upload Error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadErrorResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'

  /projects/featured:
    get:
      tags:
        - "Projects"
      summary: "Get the currently featured projects"
      parameters:
        - $ref: '#/components/parameters/Platform'
        - $ref: '#/components/parameters/MaxVersion'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeaturedProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  /projects/categories:
    get:
      tags:
        - "Projects"
      summary: "Get default number of projects per category (Most downloaded etc.)"
      parameters:
        - $ref: '#/components/parameters/MaxVersion'
        - $ref: '#/components/parameters/Flavor'
        - $ref: '#/components/parameters/Locale'
      responses:
        '200':
          description: OK
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsCategoryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  /projects/search:
    get:
      tags:
        - "Projects"
      summary: "Search for projects associated with a keywords"
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/MaxVersion'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  /projects/user:
    get:
      security:
        - BearerAuth: [ ]
      tags:
        - "Projects"
      summary: "Get the projects of the logged in user"
      parameters:
        - $ref: '#/components/parameters/MaxVersion'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/projects/user/{id}':
    get:
      tags:
        - "Projects"
      summary: "Get the public projects of a given user"
      parameters:
        - $ref: '#/components/parameters/Uuid'
        - $ref: '#/components/parameters/MaxVersion'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/projects/extensions':
    parameters:
      - $ref: '#/components/parameters/Locale'
    get:
      tags:
        - "Projects"
      summary: "Get all possible project extensions. Extensions are automatically added to projects based on their bricks."
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtensionsResponse'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/projects/tags':
    parameters:
      - $ref: '#/components/parameters/Locale'
    get:
      tags:
        - "Projects"
      summary: "Get all possible project tags. Some Tags will only be availabe during events."
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TagsResponse'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/project/{id}':
    get:
      tags:
        - "Projects"
      summary: "Get the information of a project"
      parameters:
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
    put:
      parameters:
        - $ref: '#/components/parameters/Uuid'
        - $ref: '#/components/parameters/Locale'
      security:
        - BearerAuth: [ ]
      tags:
        - "Projects"
      summary: "Update details of a project"
      description:
        "
          Update one of your projects. All attributes are optional.
          For example you can update only the description.
          Or you can update multiple attributes at once.
        "
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateProjectRequest'
      responses:
        '204':
          description: "Project successfully updated"
          # Content hack necessary else OpenAPI-generator will ignore content for error responses (hopefully fixed sometime)
          content:
            application/json:
              schema:
                type: object
        '401':
          $ref: '#/components/responses/InvalidCredentials'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '422':
          description: "Unprocessable Entity. (Specific error messages will be translated to the locale)"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProjectErrorResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '500':
          description: "Server error"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateProjectFailureResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
    delete:
      security:
        - BearerAuth: [ ]
      tags:
        - Projects
      summary: 'Delete a project'
      parameters:
        - $ref: '#/components/parameters/Uuid'
      responses:
        '204':
          description: "Project successfully deleted"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/project/{id}/catrobat':
    get:
      tags:
        - Projects
      summary: 'Download the .catrobat (=zip) file of a project'
      description: 'If the request is made by an authenticated user, further internal actions are triggered. (Download counter, ...)'
      parameters:
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: ".catrobat file successfully downloaded"
          content:
            application/zip:
              schema:
                type: string
                format: binary
                example: 'projectName.catrobat'
          headers:
            Content-Disposition:
              schema:
                type: string
                description: Used only with `application/zip` responses
                example: attachment; filename="name.catrobat"
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          description: "We were not able to create a .catrobat file for this project. There is a high possibility that the project files are missing on the server."


  '/project/{id}/report':
    post:
      security:
        - BearerAuth: [ ]
      tags:
        - Projects
      summary: 'Report a project -- StatusCode: 501 - Not yet implemented'
      parameters:
        - $ref: '#/components/parameters/Uuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectReportRequest'
      responses:
        '204':
          description: "Project successfully reported"
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/project/{id}/recommendations':
    parameters:
      - $ref: '#/components/parameters/Locale'

    get:
      tags:
        - "Projects"
      summary: "Get recommended projects related to the specific project"
      parameters:
        - $ref: '#/components/parameters/Uuid'
        - $ref: '#/components/parameters/RecommendedProjectType'
        - $ref: '#/components/parameters/MaxVersion'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
      responses:
        '200':
          description: "OK"
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  ################################################
  # Notifications
  #
  /notifications:
    parameters:
      - $ref: '#/components/parameters/Locale'
    get:
      security:
        - BearerAuth: [ ]
      tags:
        - "Notifications"
      summary: 'Get user notifications -- StatusCode: 501 - Not yet implemented'
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/NotificationsType'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'

  '/notification/{id}/read':
    parameters:
      - $ref: '#/components/parameters/Locale'
    put:
      security:
        - BearerAuth: [ ]
      tags:
        - "Notifications"
      summary: 'Mark specified notification as read'
      parameters:
        - $ref: '#/components/parameters/NotificationsId'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFound'

  /notifications/read:
    put:
      security:
        - BearerAuth: [ ]
      tags:
        - "Notifications"
      summary: 'Mark all notifications as read'
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

  /notifications/count:
    get:
      security:
        - BearerAuth: [ ]
      tags:
        - "Notifications"
      summary: 'Count the number of unseen notifications'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotificationsCountResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'

  ################################################
  # Media Library
  #
  '/media/package/{name}':
    get:
      tags:
        - "Media Library"
      summary: "Get media-library asstes of a named package"
      parameters:
        - in: path
          name: name
          schema:
            type: string
            pattern: '^[a-zA-Z0-9-_]+$'
            example: "looks"
          required: true
          description: "Name of the package"
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFilesResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/media/files':
    get:
      tags:
        - "Media Library"
      summary: 'Get *all* content of the media library.'
      parameters:
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
      responses:
        '200':
          description: "OK"
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFilesResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/media/file/{id}':
    get:
      tags:
        - "Media Library"
      summary: "Get the information of a specific media file"
      parameters:
        - in: path
          name: id
          schema:
            type: integer
            example: 123
          required: true
          description: "ID of any given media file"
        - $ref: '#/components/parameters/Attributes'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFileResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  '/media/files/search':
    get:
      tags:
        - Media Library
      summary: "Search for mediafiles associated with keywords"
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
        - $ref: '#/components/parameters/Attributes'
        - $ref: '#/components/parameters/Flavor'
        - name: package_name
          description: "In which package you want to search (for more fine tuned results)"
          example: "looks"
          in: query
          schema:
            type: string
            default: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MediaFilesResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  ######################################################
  # Search
  ###
  /search:
    get:
      tags:
        - Search
      summary: 'Search for projects, users,..'
      description: "The default is to search in all categories."
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/SearchType'
        - $ref: '#/components/parameters/Limit'
        - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'
        '400':
          $ref: '#/components/responses/BadRequest'
        '406':
          $ref: '#/components/responses/NotAcceptable'

  ################################################
  # Studios
  #
  '/studio':
    parameters:
      - $ref: '#/components/parameters/Locale'
    post:
      security:
        - BearerAuth: [ ]
      tags:
        - Studio
      summary: Create a new Studio
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateStudioRequest'
      responses:
        '201':
          description: Studio successfully created.
          headers:
            Location:
              schema:
                type: string
                example: >-
                  https://share.catrob.at/app/studio/63768cf1-5f07-11ea-a2ae-000c292a0f49
              description: Resource location on server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudioResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '422':
          description: 'Unprocessable Entity (Specific error messages will be translated to the locale)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateStudioErrorResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'

  '/studio/{id}':
    parameters:
      - $ref: '#/components/parameters/Locale'
    post:
      security:
        - BearerAuth: [ ]
      tags:
        - Studio
      summary: Update a Studio (only available to studio admins)
      parameters:
        - $ref: '#/components/parameters/Uuid'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UpdateStudioRequest'
      responses:
        '200':
          description: Studio successfully updated.
          headers:
            Location:
              schema:
                type: string
                example: https://share.catrob.at/app/studio/63768cf1-5f07-11ea-a2ae-000c292a0f49
              description: Resource location on server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudioResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'
        '422':
          description: 'Unprocessable Entity (Specific error messages will be translated to the locale)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateStudioErrorResponse'
          headers:
            X-Response-Hash:
              $ref: '#/components/headers/X-Response-Hash'
            Content-Language:
              $ref: '#/components/headers/Content-Language'

    delete:
      security:
        - BearerAuth: [ ]
      tags:
        - Studio
      summary: Delete a studio (only available to studio admins)
      parameters:
        - $ref: '#/components/parameters/Uuid'
      responses:
        '204':
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'

    get:
      tags:
        - Studio
      summary: Get studio details (private studios are only available to members)
      parameters:
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: OK
          headers:
            Location:
              schema:
                type: string
                example: https://share.catrob.at/app/studio/63768cf1-5f07-11ea-a2ae-000c292a0f49
              description: Resource location on server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudioResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/NotAcceptable'


components:

  ##############################################
  # Default Response messages
  ###
  responses:
    OK:
      description: "OK"

    NoContent:
      description: "No Content"

    UnauthorizedError:
      description: "Invalid JWT token | JWT token not found | JWT token expired"

    BadRequest:
      description: "Bad request (Invalid, or missing parameters)"

    InvalidCredentials:
      description: "Invalid credentials"

    InvalidRefreshToken:
      description: "Refresh Token expired | Refresh Token has been used more than once (single use)"

    InvalidUploadToken:
      description: "The provided deprecated upload token is invalid or has expired"

    NotAcceptable:
      description: "Not acceptable - client must accept application/json as content type"

    UnsupportedMediaType:
      description: "Unsupported Media Type - request must use application/json as content type"

    NotFound:
      description: "Not found"

    UnprocessableEntity:
      description: "Unprocessable Entity"

    InvalidIdToken:
      description: "Invalid Client ID token"

    Forbidden:
      description: "Insufficient privileges, action not allowed."

  ##############################################
  # Security Schemes
  ###
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  ##############################################
  # Request Parameters
  ###
  parameters:
    ##
    # Default
    #
    Locale:
      in: header
      name: Accept-Language
      required: false
      schema:
        type: string
        description: "ISO_639-1 or ISO_3166-1 locale of the user. Defaults internally to en"
        default: 'en'

    Uuid:
      name: id
      in: path
      schema:
        $ref: '#/components/schemas/Uuid'
      required: true

    Flavor:
      in: query
      name: flavor
      schema:
        type: string
        example: "luna"
        default: ''

    Platform:
      in: query
      name: platform
      required: false
      description: "Indication for which platform the response should be optimized (ios, android)"
      schema:
        type: string
        example: "ios"
        default: ""
        enum:
          - ""
          - "android"
          - "ios"

    Limit:
      name: limit
      in: query
      schema:
        $ref: '#/components/schemas/Limit'

    Offset:
      name: offset
      in: query
      schema:
        $ref: '#/components/schemas/Offset'

    Attributes:
      name: attributes
      in: query
      schema:
        type: string
        description: "Comma-separated list of attributes to include in the response"
        pattern: '^[a-zA-Z0-9\-_]+(,[a-zA-Z0-9\-_]+)*$'
        example: "id,name,description"
        default: ''

    RefreshToken:
      name: X-Refresh
      in: header
      description: "Refresh Token"
      schema:
        type: string
        example: "xxxxx.yyyyy.zzzzz"
      required: true

    ##
    # Notifications specific
    #
    NotificationsId:
      name: id
      in: path
      schema:
        $ref: '#/components/schemas/NotificationsId'
      required: true

    NotificationsType:
      name: type
      in: query
      schema:
        type: string
        enum:
          - "all"
          - "reaction"
          - "follow"
          - "comment"
          - "remix"
        default: "all"

    ##
    # Project specific
    #
    ProjectType:
      in: query
      name: category
      required: true
      schema:
        type: string
        enum:
          - "recent"
          - "random"
          - "most_viewed"
          - "most_downloaded"
          - "example"
          - "scratch"
          - "recommended"
          - "trending"
          - "popular"

    RecommendedProjectType:
      in: query
      name: category
      required: true
      schema:
        type: string
        enum:
          - "similar"
          - "also_downloaded"
          - "more_from_user"
      description:
        "
          * `similar` - Get similar projects to the specific project\n
          * `also_downloaded` - Get projects that users who downloaded the specific project also downloaded\n
          * `more_from_user` - Get more projects from the owner of the specific project
        "
    MaxVersion:
      name: max_version
      in: query
      schema:
        type: string
        example: '0.999'
        default: ''
      description:
        "
            Only shows project with a smaller version number than max version.\n
            `Warning!` Current implementation is kinda broken.
            To ensure correct results use the following format '[0-9].[0-9]{3}'
          "

    ##
    # Search specific
    #
    SearchType:
      name: type
      in: query
      schema:
        type: string
        default: all
        enum:
          - "all"
          - "projects"
          - "users"

  ##############################################
  # Response Headers
  ###

  headers:
    X-Response-Hash:
      schema:
        type: string
        example: '56asfd5a56sfd564a56dsf65a56sdf'
      description: 'MD5 Hash of response the body. Used for caching responses.'

    Content-Language:
      schema:
        type: string
        example: 'de_DE'
      description: 'Locale of the response content. Default: `en`'


  schemas:

    ##############################################
    # Default Schemas
    ###

    Uuid:
      type: string
      description: "Unique UUID/ID (string) of the object"
      pattern: '^[a-zA-Z0-9\-]+$'
      example: "1234abcd-12ab-12ab-12ab-123456abcdef"

    Limit:
      type: integer
      minimum: 0
      description: "How many objects should be shown at maximum"
      default: 20
      example: 3

    Offset:
      type: integer
      minimum: 0
      description: "How many objects should be skipped"
      default: 0
      example: 2

    ##############################################
    # Media Library Schemas
    ###
    MediaPackagesResponse:
      type: array
      items:
        $ref: '#/components/schemas/MediaPackageResponse'

    MediaPackageResponse:
      type: object
      properties:
        id:
          type: integer
          example: 123
          description: "ID of the package"
        name:
          type: string
          example: "Looks"
          description: "Name of the package"
        url:
          type: string
          example: "https://share.catrob.at/app/media-library/looks"
          description: "Absolute path to the package"
        categories:
          type: array
          items:
            $ref: '#/components/schemas/MediaCategoriesResponse'

    MediaCategoriesResponse:
      type: array
      items:
        $ref: '#/components/schemas/MediaCategoryResponse'

    MediaCategoryResponse:
      type: object
      properties:
        id:
          type: integer
          example: 123
          description: "ID of the category"
        name:
          type: string
          example: "Portrait"
          description: "Name of the category"
        priority:
          type: integer
          example: 10
          description: "Shows how important a category is (0 is the least priority)"
          minimum: 0

    MediaFilesResponse:
      type: array
      items:
        $ref: '#/components/schemas/MediaFileResponse'

    MediaFileResponse:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "luna_sinde_2"
        flavors:
          type: array
          items:
            type: string
          example: [ "luna", "pocketcode" ]
        packages:
          type: array
          items:
            type: string
          example: [ "Looks", "Sounds" ]
        category:
          type: string
          example: "Luna&Cat"
        author:
          type: string
          example: "CatrowebAdmin"
        extension:
          type: string
          example: "png"
        download_url:
          type: string
          example: "https://share.catrob.at/pocketcode/download-media/983.png"
        size:
          type: integer
          description: Size of the file in bytes
          example: 1048576
        file_type:
          type: string
          description: Type of the media file
          enum:
            - "project"
            - "image"
            - "sound"
            - "video"
            - "other"


    ##############################################
    # Authentication Schemas
    ###

    ## Request

    LoginRequest:
      type: object
      properties:
        username:
          type: string
          minLength: 3
          maxLength: 180
          example: "Catrobat"
          description: "Name of the user"
        password:
          type: string
          format: password
          minLength: 6
          maxLength: 4096
          example: "myPassword123"
          description: "A secure password"
    OAuthLoginRequest:
      type: object
      properties:
        id_token:
          type: string
          example: ".eydfdf23232323"
          description: "User ID token"
        resource_owner:
          type: string
          example: "google"
          description: "OAuth provider"
    RefreshRequest:
      type: object
      properties:
        refresh_token:
          type: string
          example: "xxxxx.yyyyy.zzzzz"
    UpgradeTokenRequest:
      type: object
      properties:
        upload_token:
          type: string
          example: "xxxxx.yyyyy.zzzzz"

    ## Response

    JWTResponse:
      type: object
      properties:
        token:
          type: string
          example: "xxxxx.yyyyy.zzzzz"
        refresh_token:
          type: string
          example: "xxxxx.yyyyy.zzzzz"

    ##############################################
    # UserSchemas
    ###

    ## Request

    BaseUser:
      type: object
      properties:
        email:
          type: string
          format: email
          example: "foo.bar@catrob.at"
          description: "Email of the user"
        username:
          type: string
          example: Testuser
          # no min/max specification in order to handle the errors in catroweb instead of the autogenerated controllers.
          description: 'Name of the user | minLength: 3 | maxLength: 180'
        password:
          type: string
          format: password
          example: password
          # no min/max specification in order to handle the errors in catroweb instead of the autogenerated controllers.
          description: 'A secure password | minLength: 6 | maxLength: 4096'
        picture:
          type: string
          example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…"
          description: "The profile picture of the user in data URI scheme."
        about:
          type: string
          example: "My name is Irving and I love developing games with Pocket Code!"
          description: "An introduction of the user."
        currently_working_on:
          type: string
          example: "The next awesome game!"
          description: "A short description about the project the user is currently working on."

    ResetPasswordRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          example: "foo.bar@catrob.at"
          description: "Email of the user"

    RegisterRequest:
      allOf:
        - $ref: '#/components/schemas/DryRun'
        - $ref: '#/components/schemas/BaseUser'

    UpdateUserRequest:
      allOf:
        - $ref: '#/components/schemas/DryRun'
        - $ref: '#/components/schemas/BaseUser'
        - type: object
          properties:
            current_password:
              type: string
              format: password
              example: current password
              description: 'The current password of the user. Required for changing the password.'

    ProjectReportRequest:
      type: object
      properties:
        category:
          type: string
          enum:
            - "Sexual content"
            - "Graphic violence"
            - "Hateful or abusive content"
            - "Improper content rating"
            - "Illegal prescription or other drug"
            - "Copycat or impersonation"
            - "Other objection"

    DryRun:
      type: object
      properties:
        dry_run:
          type: boolean
          default: false
          description: "Indicates if a request should only be verified or executed"

    ## Response

    UsersDataResponse:
      type: array
      items:
        $ref: '#/components/schemas/BasicUserDataResponse'

    BasicUserDataResponse:
      type: object
      properties:
        id:
          type: string
          example: "1234abcd-12ab-12ab-12ab-123456abcdef"
          description: "Unique ID of the user"
        username:
          type: string
          example: "Catroweb"
          description: "Nickname of the user"
        picture:
          type: string
          example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…"
          description: "The profile picture of the user in data URI scheme."
        about:
          type: string
          example: "My name is Irving and I love developing games with Pocket Code!"
          description: "An introduction of the user."
        currently_working_on:
          type: string
          example: "The next awesome game!"
          description: "A short description about the project the user is currently working on."
        projects:
          type: integer
          example: 4
          description: "Amount of projects of the user"
        followers:
          type: integer
          example: 11
          description: "Amount of users that follow this user"
        following:
          type: integer
          example: 42
          description: "Amount of users followed by this user"
        ranking_score:
          type: integer
          example: 151
          description: "Ranking score of this user"

    ExtendedUserDataResponse:
      allOf:
        - $ref: '#/components/schemas/BasicUserDataResponse'
        - type: object
          # all private properties
          properties:
            email:
              type: string
              format: email
              example: "foo.bar@catrob.at"
              description: "EMail of the user"

    RegisterErrorResponse:
      type: object
      properties:
        email:
          type: string
          enum:
            - "Email already in use"
            - "Email invalid"
            - "Email missing"
        username:
          type: string
          enum:
            - "Username too short"
            - "Username too long"
            - "Username already in use"
            - "Username missing"
            - "Username must not contain an email address"
        password:
          type: string
          enum:
            - "Password too short"
            - "Password too long"
            - "Password contains invalid chars"
            - "Password missing"

    UpdateUserErrorResponse:
      type: object
      properties:
        email:
          type: string
          enum:
            - "Email already in use"
            - "Email invalid"
        username:
          type: string
          enum:
            - "Username too short"
            - "Username too long"
            - "Username already in use"
            - "Username must not contain an email address"
        password:
          type: string
          enum:
            - "Password too short"
            - "Password too long"
            - "Password contains invalid chars"
        current_password:
          type: string
          enum:
            - "Current password is missing"
            - "Current password is wrong"
        picture:
          type: string
          enum:
            - "Profile picture invalid or not supported"

    ResetPasswordErrorResponse:
      type: object
      properties:
        email:
          type: string
          enum:
            - "Email invalid"
            - "Email missing"

    CreateStudioErrorResponse:
      type: object
      properties:
        name:
          type: string
          enum:
            - "Name already in use"
            - "Name missing"
            - "Name too short"
            - "Name too long"
        description:
          type: string
          enum:
            - "Description too short"
            - "Description too long"
            - "Description missing"
        image_file:
          type: string
          enum:
            - "Image size too large"
            - "Image type not supported"
            - "Image invalid"

    UpdateStudioErrorResponse:
      type: object
      properties:
        name:
          type: string
          enum:
            - "Name already in use"
            - "Name too short"
            - "Name too long"
        description:
          type: string
          enum:
            - "Description too short"
            - "Description too long"
            - "Description missing"
        image_file:
          type: string
          enum:
            - "Image size too large"
            - "Image type not supported"
            - "Image invalid"

    ######################################################
    # Project Schemas
    ###

    # Request

    ProjectUploadRequest:
      type: object
      properties:
        checksum:
          type: string
          example: "aqqoslcotroewlclcceadfgf"
          description: "Checksum of the *.catrobat file"
        file:
          type: string
          format: binary
          description: 'The *.catrobat project file'
        flavor:
          type: string
          default: "pocketcode"
          example: "pocketcode"
          description: "The flavor of this project"
        private:
          type: boolean
          description: "Indicates whether a project should be private"
          default: false
          example: false
      required:
        - checksum
        - file

    UpdateProjectRequest:
      type: object
      properties:
        name:
          type: string
          example: My amazing project
          description: 'The name of the project. minLength: 1 | maxLength: 255'
        description:
          type: string
          description: 'A description of the project.'
        credits:
          type: string
          description: 'Credits and notes for the project. E.g., credits for using ideas, scripts or artwork from other people.'
        private:
          type: boolean
          example: false
          description: 'Whether a project is publicly visible (false) or only via direct link (true).'
        screenshot:
          type: string
          example: "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ…"
          description: "An image representing the project in data URI scheme."


    ## Response

    UploadErrorResponse:
      type: object
      properties:
        error:
          type: string
          example: "There is a problem"

    UpdateProjectErrorResponse:
      type: object
      properties:
        name:
          type: string
          enum:
            - "Name empty"
            - "Name too long"
        description:
          type: string
          enum:
            - "Description too long"
        credits:
          type: string
          enum:
            - "Credits too long"
        screenshot:
          type: string
          enum:
            - "Project screenshot invalid or not supported"

    UpdateProjectFailureResponse:
      type: object
      properties:
        error:
          type: string
          enum:
            - "Failed saving details of the project."
            - "Failed reading, converting or storing the screenshot. Please check your input."

    FeaturedProjectsResponse:
      type: array
      items:
        $ref: '#/components/schemas/FeaturedProjectResponse'

    FeaturedProjectResponse:
      type: object
      properties:
        id:
          type: string
          example: 1
        project_id:
          type: string
          example: "1234abcd-12ab-12ab-12ab-123456abcdef"
        project_url:
          type: string
          example: 'http://localhost:8080/app/project/37bf6d39-3fc3-11eb-977a-0242ac120004'
        url:
          type: string
          example: 'https://example.com/project/1234'
        name:
          type: string
          example: "My example project"
        author:
          type: string
          example: "Catrobat"
        featured_image:
          type: string
          example: 'https://share.catrob.at/resources/featured/featured_999.png'

    ProjectsCategoryResponse:
      type: array
      items:
        $ref: '#/components/schemas/ProjectsCategory'

    ProjectsCategory:
      type: object
      properties:
        type:
          type: string
          example: "recent"
          description: "The name of the categories in english."
        name:
          type: string
          example: "Newest projects"
          description: "Translated name according to the language header"
        projectsList:
          type: array
          description: "Array of projects"
          items:
            $ref: '#/components/schemas/ProjectResponse'

    ProjectsResponse:
      type: array
      items:
        $ref: '#/components/schemas/ProjectResponse'

    ProjectResponse:
      type: object
      properties:
        id:
          type: string
          example: "1234abcd-12ab-12ab-12ab-123456abcdef"
          description: 'The unique identifier of the project'
        name:
          type: string
          description: 'The name of the project. minLength: 1 | maxLength: 255'
          example: "My example project"
        author:
          type: string
          description: "The name of the projects' author"
          example: "Catrobat"
        description:
          type: string
          description: 'A description of the project.'
          example: "Check out my very cool project!"
        credits:
          type: string
          description: 'Credits and notes for the project. E.g., credits for using ideas, scripts or artwork from other people.'
          example: "Special thanks to all contributors!"
        version:
          type: string
          description: "The catrobat version that was used to create this project."
          example: 0.9.66
        views:
          type: integer
          description: "The projects' count of views"
          example: 2
        download:
          type: integer
          example: 2
          deprecated: true
          description: "The projects' count of downloads. Deprecated. Use downloads"
        downloads:
          type: integer
          description: "The projects' count of downloads"
          example: 2
        reactions:
          type: integer
          description: "The projects' count of reactions"
          example: 2
        comments:
          type: integer
          description: "The projects' count of comments"
          example: 2
        private:
          type: boolean
          description: 'Whether a project is publicly visible (false) or only via direct link (true).'
          example: false
        flavor:
          type: string
          example: "pocketcode"
        tags:
          type: array
          description: 'Tags allow projects to be categorized by their creators'
          items:
            type: string
          example: [ "game", "art" ]
        uploaded:
          type: integer
          description: 'The time of the upload.'
          example: 1575562569
        uploaded_string:
          type: string
          description: 'A localised text interpretation of the uploaded timestamp'
          example: 11 minutes ago
        screenshot_large:
          type: string
          example:
            "https://share.catrob.at/resources/screenshots/screen_1234abcd-12ab-12ab-12ab-123456abcdef.png"
        screenshot_small:
          type: string
          example:
            "https://share.catrob.at/resources/thumbnails/screen_1234abcd-12ab-12ab-12ab-123456abcdef.png"
        project_url:
          type: string
          description: 'The url to the project on our official share community platform'
          example:
            "https://share.catrob.at/pocketcode/project/1234abcd-12ab-12ab-12ab-123456abcdef"
        download_url:
          type: string
          description: 'The url to GET the catrobat file of this project'
          example:
            "https://share.catrob.at/api/project/1234abcd-12ab-12ab-12ab-123456abcdef/catrobat"
        filesize:
          type: number
          example: 0.14381762458251943
          description: "The filesize of the catrobat file in megabytes"
        not_for_kids:
          type: integer
          example: 0
          description: "Indicates whether a project is suitable for kids or not (0 = safe for kids, 1 = not safe for kids, 2 = not safe for kids set by moderator)"

    ExtensionsResponse:
      type: array
      items:
        $ref: '#/components/schemas/ExtensionResponse'

    ExtensionResponse:
      type: object
      properties:
        id:
          type: string
          example: "embroidery"
          description: "The internal title of the extension"
        text:
          type: string
          example: "Embroidery"
          description: "The translated text of the project extension."


    TagsResponse:
      type: array
      items:
        $ref: '#/components/schemas/TagResponse'

    TagResponse:
      type: object
      properties:
        id:
          type: string
          example: "game"
          description: "The internal title of the title"
        text:
          type: string
          example: "Game"
          description: "The translated text of the project tag."

    ######################################################
    # Notification Schemas
    ###

    NotificationsId:
      type: integer
      minimum: 0
      description: "Id of a notification"
      default: 0
      example: 2

    NotificationsCountResponse:
      type: object
      properties:
        total:
          type: integer
          example: 9
        like:
          type: integer
          example: 1
        follower:
          type: integer
          example: 0
        comment:
          type: integer
          example: 5
        remix:
          type: integer
          example: 3

    NotificationsResponse:
      type: array
      items:
        $ref: '#/components/schemas/NotificationResponse'

    NotificationResponse:
      type: object
      properties:
        id:
          type: integer
          example: 123
          description: "Id of the notification"
        type:
          type: string
          example: "remix"
          description: "Notification Type"
        seen:
          type: boolean
          description: "Seen status of the notification"
        content:
          type: array
          items:
            $ref: '#/components/schemas/NotificationContent'

    NotificationContent:
      type: object
      properties:
        from:
          description: "Id of the user who caused the notification"
          allOf:
            - $ref: '#/components/schemas/Uuid'
        from_name:
          type: string
          example: "Catroweb"
          description: "Username of the user who caused the notification"
        project:
          description: "Id of the project for which the notification is about"
          allOf:
            - $ref: '#/components/schemas/Uuid'
        project_name:
          type: string
          example: "Awesome Game"
          description: "Name of the project for which the notification is about"
        avatar:
          type: string
          example: 'https://share.catrob.at/pocketcode/images/default/avatar_default.png'
          description: "Avatar of the user who caused the notification"
        remixed_project:
          description: "Id of the remixed project"
          allOf:
            - $ref: '#/components/schemas/Uuid'
        remixed_project_name:
          type: string
          example: "Awesome Remixed Game"
          description: "Name of the remixed project"
        message:
          type: string
          example:
            "User1 created a remix Awesome Game of your game Awesome Remixed Game."
          description: "Notification message"
        prize:
          type: string
          description: "Prize for anniversary notifications"

    ######################################################
    # Studio Schema
    ###
    CreateStudioRequest:
      type: object
      properties:
        name:
          type: string
          example:  Panda Gang
          description: 'The name of the studio (character: min 3, max 180)'
          # no min/max specification in order to handle the errors in catroweb instead of the autogenerated controllers.
        description:
          type: string
          example:  The giant panda also known as the panda bear (or simply the panda), is a bear.
          description: 'A small description about the Studio (character: min 1, max 3000)'
          # no min/max specification in order to handle the errors in catroweb instead of the autogenerated controllers.
        is_public:
          type: boolean
          example:  true
          default: true
          description: This flag sets the studios' visibility to public or private
        enable_comments:
          type: boolean
          example:  true
          default: true
          description: This flag enables or disabled the possibility to add comments to the studio
        image_file:
          type: string
          format: binary
          example: panda.png
          description: Cover image; Size limit 1MB; Supported extensions are jpeg, png, webp;

    UpdateStudioRequest:
      type: object
      properties:
        name:
          type: string
          example: Panda Gang
          description: 'The name of the studio (character: min 3, max 180)'
          # no min/max specification in order to handle the errors in catroweb instead of the autogenerated controllers.
        description:
          type: string
          example: The giant panda also known as the panda bear (or simply the panda), is a bear.
          description: 'A small description about the Studio (character: min 1, max 3000)'
          # no min/max specification in order to handle the errors in catroweb instead of the autogenerated controllers.
        is_public:
          type: boolean
          example: true
          description: This flag sets the studios' visibility to public or private
        enable_comments:
          type: boolean
          example: true
          description: This flag enables or disabled the possibility to add comments to the studio
        image_file:
          type: string
          format: binary
          example: panda.png
          description: Cover image; Size limit 1MB; Supported extensions are jpeg, png, webp;

    StudioResponse:
      type: object
      properties:
        id:
          type: string
          description: ID of the studio
          example: 1234abcd-12ab-12ab-12ab-123456abcdef
        name:
          type: string
          example:  Panda Gang
          description: The name of the studio
        description:
          type: string
          example:  The giant panda also known as the panda bear (or simply the panda), is a bear.
          description: A small description about the Studio
          default: ""
        is_public:
          type: boolean
          example:  true
          default: true
          description: This flag sets the studios' visibility to public or private
        enable_comments:
          type: boolean
          example:  true
          default: true
          description: This flag enables or disabled the possibility to add comments to the studio
        image_path:
          type: string
          example: https://share.catrob.at/resources/studio/panda.png
          description: Cover image

    ######################################################
    # Utility Schemas
    ###
    SurveyResponse:
      type: object
      properties:
        url:
          type: string
          example: https://www.surveylegend.com/survey/#/d29yZHByZXNzMTQzODU2~-MRPPYfbYj7-rPUTK3HH
          description: Url to a survey for the given language

    ######################################################
    # Search Schemas
    ###
    SearchResponse:
      type: object
      properties:
        projects:
          type: array
          description: "Array of projects"
          items:
            $ref: '#/components/schemas/ProjectResponse'
        projects_total:
          type: integer
          example: 15
        users:
          type: array
          description: "Array of users"
          items:
            $ref: '#/components/schemas/BasicUserDataResponse'
        users_total:
          type: integer
          example: 15