openapi.yaml

openapi: 3.0.0
servers:
- url: https://forge.api.prod-preview.openshift.io/creator/
  description: Development server
- url: https://forge.api.openshift.io/creator/
  description: Production server
- url: http://localhost:8081
  description: Local Development
- url: http://localhost:8080
  description: Local Dist

info:
  version: "1.0.0"
  title: Launcher Creator Backend API
  description: >-
    This document defines the REST endpoints exposed by the
    launcher-creator-backend component

security:
- application:
  - read
  - write

paths:
  /enums:
    get:
      summary: Returns all available enumeration definitions
      security: []
      description: >-
        This endpoint returns all known enumerations
      tags:
      - catalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enumerations'
  /enums/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      summary: Returns the selected enumeration definition
      security: []
      description: >-
        This endpoint returns a given enumeration
      tags:
      - catalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Enumeration'
  /capabilities:
    get:
      summary: Returns the available Capabilities
      security: []
      description: >-
        This endpoint returns all known Capabilities
      tags:
      - catalog
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Capabilities'
  /zip:
    post:
      summary: Create ZIP containing a generated project and returns and id to download it
      security: []
      description: >-
        This endpoint returns and id to download the ZIP containing code that was
        generated using the specified Capabilities
      tags:
      - project
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ZipRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    description: The id to download the zip
                    type: string
        '400':
          description: Bad Request
  /download:
    get:
      summary: Returns a ZIP containing a generated project for the specified id
      security: []
      description: >-
        This endpoint returns a ZIP containing a generated project for the specified id
      tags:
      - project
      parameters:
      - name: id
        in: query
        required: true
        schema:
          type: string
        description: The id returned by the zip method
      responses:
        '200':
          description: OK
          content:
            application/zip: {}
        '404':
          description: Not Found
  /launch:
    post:
      summary: Pushes a generated project to GitHub and OpenShift
      security:
      - bearerAuth: []
      description: >-
        This endpoint pushes code that was generated using the specified
        Capabilities to a user's GitHub and OpenShift accounts
      tags:
      - project
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LaunchRequest'
      responses:
        '200':
          description: OK
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
  /import/branches:
    get:
      summary: Lists all available branches and tags for the given Git repository
      description: >-
        Takes a Git repositor URL and returns the names of all the branches and tags
      tags:
        - import
      parameters:
        - name: gitImportUrl
          in: query
          required: true
          schema:
            type: string
          description: The URL to the Git repository
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /import/analyze:
    get:
      summary: Analyzes the given Git repository and returns what S2I builder image to use
      description: >-
        Takes a Git repositor URL and looks at the code inside it to determine what OpenShift
        S2I builder could be used to compile and run it
      tags:
        - import
      parameters:
        - name: gitImportUrl
          in: query
          required: true
          schema:
            type: string
          description: The URL to the Git repository to analyze
        - name: gitImportBranch
          in: query
          schema:
            type: string
          description: The branch of the Git repository to analyze (defaults to "master")
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalysisResult'
  /import/launch:
    post:
      tags:
        - import
      summary: Deploys an existing codebase on OpenShift
      description: Deploys an existing codebase on OpenShift
      parameters:
        - name: applicationName
          in: query
          description: The name of the application to be created
          required: true
          schema:
            type: string
        - name: gitImportUrl
          in: query
          description: A URL to the git repository to import
          required: true
          schema:
            type: string
        - name: gitImportBranch
          in: query
          schema:
            type: string
          description: The branch of the Git repository to analyze (defaults to "master")
        - name: builderImage
          in: query
          description: The name of the image to use for building and running the code
          schema:
            type: string
        - name: builderLanguage
          in: query
          description: The language to use for building and running the code
          schema:
            type: string
      responses:
        '200':
          description: OK

components:
  schemas:
    Enumeration:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        icon:
          type: string
        metadata:
          type: object

    Enumerations:
      type: array
      items:
        $ref: '#/components/schemas/Enumeration'

    Capabilities:
      type: array
      items:
        type: object
        properties:
          module:
            type: string
          name:
            type: string
          description:
            type: string
          props:
            type: array
            items:
              type: object
              properties:
                id:
                  type: string
                name:
                  type: string
                description:
                  type: string
                type:
                  type: string
                required:
                  type: boolean

    ZipRequest:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/Application'
      required:
      - project

    LaunchRequest:
      type: object
      properties:
        project:
          $ref: '#/components/schemas/Application'
        clusterId:
          description: The OpenShift cluster to use
          type: string
        projectName:
          description: The OpenShift project name to be used
          type: string
        gitOrganization:
          description: The Git Organization to push the code
          type: string
        gitRepository:
          description: The Git Repository to push the code
          type: string
      required:
      - project
      - clusterId
      - projectName
      - gitOrganization
      - gitRepository

    Application:
      type: object
      properties:
        application:
          description: The application name to use for the project
          type: string
        parts:
          description: The application parts to use for the project
          type: array
          items:
              type: object
              properties:
                subFolderName:
                  description: The (optional) name of the subfolder to use for the capabilities
                  type: string
                shared:
                  description: The shared properties that get applied to each selected Capability
                  type: object
                  properties:
                    runtime:
                      description: The runtime to use for the project
                      type: object
                      properties:
                        name:
                          description: The name of the runtime
                          type: string
                        version:
                          description: The version of the runtime
                          type: string
                      required:
                      - name
                capabilities:
                  description: The capabilities to add to the project
                  type: array
                  items:
                    type: object
                    properties:
                      module:
                        description: The id of the selected Capability
                        type: string
                      props:
                        description: The properties for the selected Capability
                        type: object
                    required:
                    - module
              required:
              - capabilities
      required:
      - application
      - parts

    AnalysisResult:
      type: object
      properties:
        image:
          type: string
        builderImages:
          type: array
          items:
            $ref: '#/components/schemas/Enumeration'

  securitySchemes:
    bearerAuth:            # arbitrary name for the security scheme
      type: http
      scheme: bearer
      bearerFormat: JWT    # optional, arbitrary value for documentation purposes