openapi: 3.0.0
info:
  description: 'Access token should be sent along with every request to SITE_NAME API in authorization header: `Authorization: Bearer <Token>` <br> This token can either be acquired via `auth/login` endpoint or from account settings page on [SITE_NAME website](SITE_URL/account/settings).'
  version: '1.0.0'
  title: SITE_NAME API
security:
  - accessToken: []
tags:
  - name: Projects
  - name: Auth
    description: Authenticate requests to the API
paths:
  /projects:
    post:
      tags:
        - Projects
      summary: Create a new project
      operationId: createProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrupdateProjectPayload'

      responses:
        '200':
          description: On success, the response body contains the created project in JSON format
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  project:
                    $ref: '#/components/schemas/ProjectModel'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'
    get:
      tags:
        - Projects
      summary: List all of your projects
      operationId: getAllProjects
      parameters:
        - name: perPage
          in: query
          description: How many projects to return per page
          schema:
            type: 'integer'
            default: 20
        - name: page
          in: query
          description: Which page to return
          schema:
            type: 'integer'
            default: 1
        - name: query
          in: query
          description: Filter projects by specified search query
          schema:
            type: string
        - name: published
          in: query
          description: Show only published or unpublished projects
          schema:
            type: boolean
            default: null
      responses:
        '200':
          description: Response body contains a paginated list of projects in JSON format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  pagination:
                    allOf:
                      - $ref: '#/components/schemas/Pagination'
                      - type: object
                        properties:
                          data:
                            type: array
                            items:
                              $ref: '#/components/schemas/ProjectModel'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'

  /projects/{id}/toggle-state:
    parameters:
      - name: id
        in: path
        description: ID of the project
        example: 1
    post:
      tags:
        - Projects
      summary: Publish or unpublish the project
      operationId: toggleProjectState
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                published:
                  type: boolean
                  example: true

      responses:
        '200':
          description: On success, the response body contains the project object in JSON format
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  project:
                    $ref: '#/components/schemas/ProjectModel'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'

  /projects/{id}/export/ftp:
    parameters:
      - name: id
        in: path
        description: ID of the project
        example: 1
    post:
      tags:
        - Projects
      summary: Export project to specified FTP server
      operationId: projectExportFtp
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExportToFtpPayload'

      responses:
        '200':
          description: Project was exported to FTP successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'

  /projects/{id}/download:
    parameters:
      - name: id
        in: path
        description: ID of the project
        example: 1
    get:
      tags:
        - Projects
      summary: Download specified project as a .zip file
      operationId: projectDownload

      responses:
        '200':
          description: Download the .zip file

        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '404':
          $ref: '#/components/schemas/404-Response'

  /projects/{id}:
    parameters:
      - name: id
        in: path
        description: ID of the project
        example: 1
    get:
      tags:
        - Projects
      summary: Get specified project's details
      operationId: getProject
      responses:
        '200':
          description: Response body contains a project object in JSON format.
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  project:
                    $ref: '#/components/schemas/BuilderProject'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
    put:
      tags:
        - Projects
      summary: Update specified project details
      operationId: updateProject
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CrupdateProjectPayload'
      responses:
        '200':
          description: On success, the response body contains the updated project object in JSON format
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  project:
                    $ref: '#/components/schemas/ProjectModel'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'
  /projects/{ids}:
    parameters:
      - in: path
        name: ids
        required: true
        description: Comma separated list of project IDs
        schema:
          type: string
          example: 1,2,3
    delete:
      tags:
        - Projects
      summary: Delete projects
      operationId: deleteProject
      responses:
        '200':
          description: Projects have been deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'

  /auth/register:
    post:
      security: []
      tags:
        - Auth
      summary: Register for a new account
      operationId: register
      responses:
        '200':
          description: User registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: 'example@gmail.com'
                password:
                  type: string
                  example: password
                device_name:
                  type: string
                  example: 'iphone 12'
  /auth/login:
    post:
      security: []
      tags:
        - Auth
      summary: Get access token
      description: 'Logs in specified user and returns user object along with access token. <br><br> Access Token is a string that enables SITE_NAME to verify that a request belongs to an authorized session. This token should be sent along with every request to SITE_NAME API in a authorization header: `Authorization: Bearer <Token>`.'
      operationId: login
      responses:
        '200':
          description: Operation successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
                  user:
                    $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/schemas/401-Response'
        '403':
          $ref: '#/components/schemas/403-Response'
        '422':
          description: Invalid data specified
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/422-Response'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  example: 'example@gmail.com'
                password:
                  type: string
                  example: 'password'
                device_name:
                  type: string
                  example: 'iphone 12'
components:
  schemas:
    Pagination:
      type: object
      properties:
        current_page:
          type: integer
          format: int64
          example: 1
        from:
          type: integer
          format: int64
          example: 1
        to:
          type: integer
          format: int64
          example: 100
        per_page:
          type: integer
          format: int64
          example: 25
        last_page:
          type: integer
          format: int64
          example: 156
        total:
          type: integer
          format: int64
          example: 264

    ProjectModel:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: My project
          description: Project's name.
        slug:
          type: string
          example: my-project
          description: Slug for the project.
        template:
          type: string
          description: Name of the template project was created with.
        published:
          type: boolean
          default: true
          description: Whether project is publicly accessible.
        created_at:
          type: string
          example: '2021-05-24 18:03:59'
          description: Date project was created at.
        updated_at:
          type: string
          example: '2021-05-24 18:03:59'
          description: Date project was last updated.

    BuilderProject:
      type: object
      properties:
        model:
          $ref: '#/components/schemas/ProjectModel'
        css:
          type: string
          description: Custom css addded to project by user.
        js:
          type: string
          description: Custom js addded to project by user.
        pages:
          type: array
          description: List of project pages.
          items:
            type: object
            properties:
              name:
                type: string
              html:
                type: string
                description: full production ready html for the page.

    CrupdateProjectPayload:
      type: object
      properties:
        name:
          type: string
          example: My new project
          description: Name for the project
        slug:
          type: string
          nullable: true
          description: Slug project the project. If none is provided, it will be auto generated from project name.
        css:
          type: string
          nullable: true
          description: Custom css that should be included in the project.
        js:
          type: string
          nullable: true
          description: Custom js that should be included in the project.
        template_name:
          type: string
          nullable: true
          description: Name of the template to apply to this project.
        published:
          type: boolean
          nullable: true
          default: true
          description: Whether project is publicly accessible.

    ExportToFtpPayload:
      type: object
      properties:
        host:
          type: string
          example: ftp.server.com
          description: Hostname of the FTP server.
        username:
          type: string
          example: user
          description: Username that should be used to login to FTP server.
        password:
          type: string
          example: password
          description: Password that should be used to login to FTP server.
        port:
          type: string
          example: 21
          default: 21
          nullable: true
          description: Port that should be used to login to FTP server.
        root:
          type: string
          example: /some/folder
          description: Folder where project files should be stored on FTP server.
        sssl:
          type: boolean
          nullable:  true
          default: false
          description: Whether SSL should be used to connect to FTP server.

    CustomDomain:
      type: object
      properties:
        host:
          type: string
          example: htts://example.com
          description: Fully qualified url for the custom domain.
        global:
          type: boolean
          example: false
          description: whether this domain is marked as global.

    User:
      type: object
      properties:
        id:
          type: integer
          format: int64
        display_name:
          type: string
        avatar:
          type: string
    Tag:
      type: object
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: favorites

    401-Response:
      description: Unauthenticated. Either access token is not provided or is invalid.
    403-Response:
      description: Unauthorized access. You don't have permissions required to perform this operation.
    404-Response:
      description: Resource not found. Could not find a resource with specified name or ID.
    422-Response:
      type: object
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          example: 'Reason for the error'
        errors:
          type: object
          properties:
            some_data_1:
              type: string
              example: Error message for data 1
            some_data_2:
              type: string
              example: Error message for data 2

  securitySchemes:
    accessToken:
      type: http
      scheme: bearer
