api.yaml

openapi: 3.0.2
info:
  title: Catroweb API
  description: API for the Catrobat Share Platform
  version: 0.0.1
  termsOfService: "http://example.com/terms/"
  contact:
    name: "Catrobat"
    url: "https://share.catrob.at"
    email: "webmaster@catrobat.org"
servers:
  - url: 'https://share.catrob.at/app/api/v2'
    description: Main production server
  - url: 'https://web-test.catrob.at/app/api/v2'
    description: WEB test server (might be unstabe)
  - url: 'android/test/server.at'
    description: ANDROID test server
tags:
- name: "Security"
  description: "Everything related to security"
- name: "Projects"
  description: "Everything related to projects"
- name: "Media Library"
  description: "Everything related to the media library"
paths:
  /checkToken:
    post:
      tags:
        - Security
      summary: Checking token
      description: Endpoint giving information if a given token is valid or not
      requestBody:
              required: true
              content:
                application/json:
                  schema:
                    type: object
                    properties:
                      username:
                        type: string
                        example: "username"
                      token:
                        type: string
                        example: "asd"

      responses:
        '200':
            description: OK - Sent token is valid for the given username
        '400':
            description: NOT OK - Sent token is NOT valid for the given username
  /registerUser:
    post:
      tags:
        - Security
      summary: Registering a user
      description: Registering a user. For validation purposes look at the /registerValidation API
      requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Register'
      responses:
        '200':
            description: OK - User registered
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/APIValidationResponse'
        '400':
            description: NOT OK - User not registered
  /registerValidation:
    post:
      tags:
        - Security
      summary: Validation of user input in the registration process
      description: Registering a user. 0 - 4 possible values can be given.
      requestBody:
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Register'

      responses:
        '200':
            description: OK - User validated
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/APIValidationResponse'
        '400':
            description: Malformed request body
  /login:
    post:
      tags:
        - Security
      summary: Login a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Login'
      responses:
        '200':
          description: OK
          content:
              application/json:
                schema:
                  $ref: '#/components/schemas/LoginResponseOK'
        '400':
          description: NOT OK (i.e., password invalid)

  /logout:
      post:
        tags:
          - Security
        summary: Log out a user
        requestBody:
          required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Logout'
        responses:
          '200':
            description: OK
          '400':
            description: NOT OK (i.e, token invalid)
  /media/package/{packageName}:
      get:
        tags:
          - Media Library
        summary: Get media-library asstes of a named package
        parameters:
          - in: path
            name: packageName
            schema:
              type: string
              example: looks
            required: true
            description: Name of the package
        responses:
          '200':
            description: Valid request
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Packages'
          '404':
            description: Package name not found
  /projects/featured:
      get:
        tags:
          - Projects
        summary: Get the currently featured projects
        parameters:
          - name: platform
            in: query
            schema:
              type: string
              description: Indication what platform should be used (iOs, android)
              enum: [android, iOS]
              example: 
                - android
          - name: max_version
            in: query
            schema:
              type: string
              description: "Only shows project with a smaller version number than max version"
              example: "0.999"
          - name: limit
            in: query
            schema:
              type: integer
              description: "How many featured projects should be shown at maximum"
              example: 3
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/FeaturedProjects'
  /projects/recent:
      get:
        tags:
          - Projects
        summary: Get the most recent programs
        parameters:
          - name: max_version
            in: query
            schema:
              type: string
              description: "Only shows project with a smaller version number than max version"
              example: "0.999"
          - name: limit
            in: query
            schema:
              type: integer
              description: "How many featured projects should be shown at maximum"
              default: 20
              example: 10
          - name: offset
            in: query
            schema:
              type: integer
              description: "How many featured projects should be shown at maximum"
              default: 0
              example: 10
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Projects'
  /projects/mostDownloaded:
      get:
        tags:
          - Projects
        summary: Get the most downloaded projects
        parameters:
          - name: max_version
            in: query
            schema:
              type: string
              description: "Only shows project with a smaller version number than max version"
              example: "0.999"
          - name: limit
            in: query
            schema:
              type: integer
              description: "How many projects should be shown at maximum"
              default: 20
              example: 10
          - name: offset
            in: query
            schema:
              type: integer
              description: "How many projects should be shown at maximum"
              default: 0
              example: 10
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Projects'
  /projects/mostViewed:
      get:
        tags:
          - Projects
        summary: Get the most viewed projects
        parameters:
          - name: max_version
            in: query
            schema:
              type: string
              description: "Only shows project with a smaller version number than max version"
              example: "0.999"
          - name: limit
            in: query
            schema:
              type: integer
              description: "How many projects should be shown at maximum"
              default: 20
              example: 10
          - name: offset
            in: query
            schema:
              type: integer
              description: "How many projects should be shown at maximum"
              default: 0
              example: 10
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Projects'
  /projects/randomPrograms:
      get:
        tags:
          - Projects
        summary: Get random projects
        parameters:
          - name: max_version
            in: query
            schema:
              type: string
              description: "Only shows project with a smaller version number than max version"
              example: "0.999"
          - name: limit
            in: query
            schema:
              type: integer
              description: "How many projects should be shown at maximum"
              default: 20
              example: 10
          - name: offset
            in: query
            schema:
              type: integer
              description: "How many projects should be shown at maximum"
              default: 0
              example: 10
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Projects'
  /projects/search:
      get:
        tags:
          - Projects
        summary: Search for programs associated with a keywords
        parameters:
          - name: query
            in: query
            schema:
              type: string
              description: String to be searched
          - name: max_version
            in: query
            schema:
              type: string
              description: "Only shows project with a smaller version number than max version"
              example: "0.999"
          - name: limit
            in: query
            schema:
              type: integer
              description: "How many projects should be shown at maximum"
              default: 20
              example: 10
          - name: offset
            in: query
            schema:
              type: integer
              description: "How many projects should be given in addition to limit"
              default: 0
              example: 10
        responses:
          '200':
            description: OK
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Projects'
  /projects/upload:
    post:
      tags:
        - Projects
      summary: Upload a catrobat program
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                token:
                  type: string
                  example: "asd"
                  description: "Upload token of the user"
                checksum:
                  type: string
                  example: "asd"
                  description: "Checksum of the *.catrobat file"
                file:
                  type: string
                  format: binary
                  description: "*.catrobat file"
                flavor:
                  type: string
                  example: "pocketcode"
                  default: "pocketcode"
                  description: "The flavor the uploaded program is associated with."
      responses:
        '200':
          description: Upload OK
        '400':
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UploadError'

  /projects/user/{user_id}:
      get:
        tags:
          - Projects
        summary: Get the projects of a user, if user is logged in, then there will also be private programs
        parameters:
          - in: path
            name: user_id
            schema:
              type: string
              example: "1234abcd-12ab-12ab-12ab-123456abcdef"
            required: true
            description: UUID/ID of any given user
          - name: max_version
            in: query
            description: "Only shows project with a smaller version number than max version"
            schema:
              type: string
              example: "0.999"  
          - name: limit
            in: query
            description: "How many projects should be shown at maximum"
            schema:
              type: integer
              default: 20
              example: 10
          - name: offset
            in: query
            description: "How many projects should be shown at maximum"
            schema:
              type: integer
              example: 10
          - name: token
            in: query
            description: "Token of the user -> when provided private programs will be shown too"
            schema:
              type: string
              example: "1234abcd-12ab-12ab-12ab-123456abcdef"
        responses:
          '200':
            description: Valid request
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Projects'
          '404':
            description: User does not exist
            
  /project/{project_id}:
   get:
      tags:
        - Projects
      summary: Get the information of a project
      parameters:
        - in: path
          name: project_id
          schema:
            type: string
            example: "1234abcd-12ab-12ab-12ab-123456abcdef"
          required: true
          description: UUID/ID of any given project
      responses:
          '200':
            description: Valid request
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/Project'
          '404':
            description: Project does not exist
components:
  schemas:
    UploadError:
      type: object
      properties:
        status:
          type: integer
          example: 418
        error:
          type: string
          enum: [Token invalid, Checksum invalid, ZIP invalid, XML invalid, Flavor invalid]
          example: 
            - Checksum invalid 
            - XML invalid
          
    APIValidationResponse:
      type: object
      properties:
        status:
          type: integer
          example: 418
          description: Statuscode if validation was successfull or yielded errors (200 or 400)
        email:
          type: string
          example: 
            - EMail not valid
            - EMail already in use!
        username:
          type: string
          example: 
            - Username too short! 
            - Username already in use!
        password:
          type: string
          example: 
            - Password too short
            - Password contains invalid chars
    Register:
      type: object
      properties:
        email:
          type: string
          example: "test@test.lan"
          description: EMail of the user. Validation via /registerValidation
        username:
          type: string
          example: "Testuser"
          description: Username. Validation via /registerValidation
        password:
          type: string
          example: "password"
          description: A secure password. Validation via /registerValidation
        locale:
          type: string
          example: "de"
          description: The locale, in which the answer message shoudl be translated. If not given default will be "en".
    Login:
      type: object
      properties:
        username:
          type: string
          example: "Testuser"
          description: Username. Validation via /registerValidation
        password:
          type: string
          example: "password"
          description: A secure password. Validation via /registerValidation
    LoginResponseOK:
      type: object
      properties:
        token:
          type: string
          example: "asd"
    Logout:
      type: object
      properties:
        username:
          type: string
          example: "Testuser"
          description: Username. Validation via /registerValidation
        token:
          type: string
          example: "asd"
          description: Token of the user.
    Packages:
      type: array
      items:
        $ref: '#/components/schemas/Package'

    Package:
      type: object
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: "luna_sinde_2"
        flavor:
          type: string
          example: "luna"
        package:
          type: string
          example: "Looks"
        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"
    FeaturedProjects:
      type: array
      items:
        $ref: '#/components/schemas/FeaturedProject'
    FeaturedProject:
      type: object
      properties:
        id:
          type: string
          example: "1234abcd-12ab-12ab-12ab-123456abcdef"
        name:
          type: string
          example: "My example of a Program"
        author:
          type: string
          example: "Admin"
        featured_image:
          type: string
          example: "https://share.catrob.at/resources/featured/featured_999.png"
    Projects:
      type: array
      items:
        $ref: '#/components/schemas/Project'
    Project:
      type: object
      properties:
        id:
          type: string
          example: "1234abcd-12ab-12ab-12ab-123456abcdef"
        name:
          type: string
          example: "My example of a Program"
        author:
          type: string
          example: "Admin"
        description:
          type: string
          example: "My very cool program!"
        version:
          type: string
          example: "0.9.66"
        views:
          type: integer
          example: 2
        download:
          type: integer
          example: 2
        private:
          type: boolean
          example: false
        uploaded:
          type: integer
          example: 1575562569
        uploaded_string:
          type: string
          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"
        projectUrl:
          type: string
          example: "https://share.catrob.at/pocketcode/project/1234abcd-12ab-12ab-12ab-123456abcdef"
        downloadUrl:
          type: string
          example: "https://share.catrob.at/pocketcode/download/1234abcd-12ab-12ab-12ab-123456abcdef.catrobat"
        filesize:
          type: number
          example: 0.14381762458251943
          description: 'filesize in megabytes'