openapi: 3.0.2
info:
  title: Challenge Service
  version: 0.1.0
  description: |
    A Challenge is an interesting and rewarding way to assess skills and 
    knowledge. It's centered around a set of exercises, that together lead
    the user towards some meaningful achievement.

    # Introduction

    A challenge should be an inspiring way to test someone, not a grueling 
    event. With that being said, what might be a grueling event for someone 
    might be incredibly inspiring for someone else. For this reason, it's 
    important not to generalize, and to encourage diversity and allow for 
    different ways of designing challenges.

    This service allows us to do all the basic operations we need for our 
    challenges. 

    # Authentication

    This API supports OAuth2, and more specifically, the implicit flow.

    <!-- ReDoc-Inject: <security-definitions> -->
  contact:
    name: Developer @Sci-Code
    url: 'https://sci-code.com'
    email: developer@sci-code.com
  license:
    name: Copyright © Sci-Code Inc. All Rights Reserved
    url: 'https://sci-code.com'
tags:
  - name: Challenges
    description: |-
      The ```Challenge``` object holds the information that
      describes a particular challenge. In particular, it deals 
      with how challenges will be displayed in the catalog.
paths:
  /challenges:
    post:
      summary: Create a Challenge
      operationId: createChallenge
      description: Creates a new Challenge object.
      security:
        - OAuth2:
            - 'write:challenges'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ChallengeDTO'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeDTO'
        '400':
          $ref: '#/components/responses/400_bad_request'
        '401':
          $ref: '#/components/responses/401_unauthorized'
        '403':
          $ref: '#/components/responses/403_forbidden'
      tags:
        - Challenges
    get:
      summary: List all challenges
      operationId: retrieveChallengeList
      description: Returns a list of your challenges.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChallengeDTO'
        '400':
          $ref: '#/components/responses/400_bad_request'
        '404':
          $ref: '#/components/responses/404_not_found'
      tags:
        - Challenges
  '/challenges/{id}':
    parameters:
      - name: id
        description: The unique identifier for the challenge.
        schema:
          type: string
        in: path
        required: true
    get:
      summary: Retrieve a Challenge
      operationId: retrieveChallenge
      description: 'Retrieves the details of an existing challenge. Simply supply a unique challenge ID, and you''ll get the corresponding challenge information in return.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChallengeDTO'
        '400':
          $ref: '#/components/responses/400_bad_request'
        '404':
          $ref: '#/components/responses/404_not_found'
      tags:
        - Challenges
    put:
      summary: Update a Challenge
      operationId: updateChallenge
      description: 'Updates specific details of an existing challenge. Simply supply a unique challenge ID, and the updated fields of the challenge object in the request body.'
      security:
        - OAuth2:
            - 'write:challenges'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChallengeDTO'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ChallengeDTO'
        '400':
          $ref: '#/components/responses/400_bad_request'
        '401':
          $ref: '#/components/responses/401_unauthorized'
        '403':
          $ref: '#/components/responses/403_forbidden'
        '404':
          $ref: '#/components/responses/404_not_found'
      tags:
        - Challenges
components:
  schemas:
    ChallengeDTO:
      allOf:
        - $ref: '#/components/schemas/Challenge'
    id:
      description: Unique identifier for the object.
      type: string
      example: _ZZrEOIjc2kK3159uVMqxdw
    object:
      description: String representing the object’s type. Objects of the same type share the same value.
      type: string
    timestamp:
      description: Date and Time at which the object was created. Measured in seconds since the Unix epoch.
      type: integer
      format: int64
      example: 1581554917050
      minimum: 0
    userId:
      description: Unique identifier for a user.
      type: string
      example: auth0|5e34cd09afb6530e2a739a9f
    url:
      description: 'A universal resource identifier (URI), according to the [RFC3986](https://tools.ietf.org/html/rfc3986) standard.'
      type: string
      format: uri
      example: 'https://example.com/some/path'
    fileUpload:
      type: string
      format: binary
    language:
      description: 'A three-letter ISO code ([ISO 639-3](https://en.wikipedia.org/wiki/ISO_639-3)), representing the language.'
      type: string
      minLength: 3
      maxLength: 3
      example: eng
    ExpressionTypes:
      title: type
      description: Different kinds of expressions.
      enum:
        - text
        - math
        - code
        - image
        - audio
        - animation
        - video
      type: string
    Expression:
      title: Expression
      description: An expression is a captured moment of menaingful communication - in a speficic medium and/or form.
      type: object
      properties:
        id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/id'
        created:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/timestamp'
        creator:
          $ref: '#/components/schemas/userId'
        type:
          $ref: '#/components/schemas/ExpressionTypes'
      required:
        - type
    TextExpression:
      title: Text Expression
      description: Expressions captured in rich text.
      allOf:
        - $ref: '#/components/schemas/Expression'
        - type: object
          properties:
            content:
              title: content
              description: The content in ready-to-go cleartext format.
              type: string
              example: 'Hey ho, this is some text in *markdown* format.'
            language:
              $ref: '#/components/schemas/language'
            format:
              title: format
              description: The text format.
              enum:
                - markdown
                - plain text
              type: string
              default: markdown
              example: markdown
            type:
              allOf:
                - $ref: '#/components/schemas/ExpressionTypes'
                - example: text
          required:
            - content
            - format
            - language
    MathExpression:
      title: Math Expression
      description: Expressions captured in mathematical notation.
      allOf:
        - $ref: '#/components/schemas/Expression'
        - type: object
          properties:
            content:
              title: content
              description: The mathematics content.
              type: string
              example: '\\f{a} = \\int_{-\\infty}^\\infty \\hat \\f\\xi\\,e^{2 \\pi i \\xi x} \\,d\\xi'
            format:
              title: format
              description: The mathematical notation format.
              enum:
                - katex
                - tex
              type: string
              example: katex
            type:
              allOf:
                - $ref: '#/components/schemas/ExpressionTypes'
                - example: math
          required:
            - content
            - format
    ProgrammingLanguage:
      title: ProgrammingLanguage
      description: A structure of the programming langague
      type: object
      properties:
        name:
          title: name
          description: The name of the programming language.
          type: string
        logoUrl:
          title: logoUrl
          description: A url to the logo of the language.
          type: string
      required:
        - logoUrl
        - name
    CodeExpression:
      title: Code Expression
      description: Expressions captured in various coding languages.
      allOf:
        - $ref: '#/components/schemas/Expression'
        - type: object
          properties:
            content:
              title: content
              description: The code content.
              type: string
              example: 'function f(x,y) {\n  return x+y;\n}\n'
            programmingLanguage:
              $ref: '#/components/schemas/ProgrammingLanguage'
            type:
              allOf:
                - $ref: '#/components/schemas/ExpressionTypes'
                - example: code
          required:
            - programmingLanguage
            - content
    File:
      title: File
      type: object
      description: An object with information about a file.
      properties:
        id:
          $ref: '#/components/schemas/id'
        created:
          $ref: '#/components/schemas/timestamp'
        title:
          description: A user friendly title for the file.
          maxLength: 280
          nullable: true
          type: string
        filename:
          description: 'A filename for the file, suitable for saving to a filesystem.'
          nullable: true
          type: string
        type:
          description: String representing the object's type. Objects of the same type share the same value.
          enum:
            - file
          type: string
          example: file
        size:
          description: The size in bytes of the file object.
          type: integer
        fileFormat:
          title: fileFormat
          description: The specific information encoding method used.
          enum:
            - jpg
            - png
          nullable: true
          type: string
        url:
          description: The URL from which the file can be downloaded using your live secret API key.
          type: string
      required:
        - id
        - created
        - type
        - url
        - size
    BlobExpressions:
      description: Common properties for Expressions holding binary large objects.
      type: object
      properties:
        src:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/File'
        file:
          writeOnly: true
          allOf:
            - $ref: '#/components/schemas/fileUpload'
    ImageExpression:
      title: Image Expression
      description: Expressions captured in image form.
      allOf:
        - $ref: '#/components/schemas/Expression'
        - $ref: '#/components/schemas/BlobExpressions'
        - type: object
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/ExpressionTypes'
                - example: image
          required:
            - fileFormat
            - src
    AudioExpression:
      title: Audio Expression
      description: Expressions captured in the form of sound.
      allOf:
        - $ref: '#/components/schemas/Expression'
        - $ref: '#/components/schemas/BlobExpressions'
        - type: object
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/ExpressionTypes'
                - example: audio
    AnimationExpression:
      title: Animation Expression
      description: Expressions captured in image sequence form; without sound.
      allOf:
        - $ref: '#/components/schemas/Expression'
        - $ref: '#/components/schemas/BlobExpressions'
        - type: object
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/ExpressionTypes'
                - example: animation
    VideoExpression:
      title: Video Expression
      description: Expressions captured in video form.
      allOf:
        - $ref: '#/components/schemas/Expression'
        - $ref: '#/components/schemas/BlobExpressions'
        - type: object
          properties:
            type:
              allOf:
                - $ref: '#/components/schemas/ExpressionTypes'
                - example: video
    ExerciseTypes:
      title: type
      description: Different kinds of exercises.
      type: string
      enum:
        - free_form
        - multiple_choice
        - fill_in_the_blank
        - command_line
        - code_snippet
        - codebase
        - database
        - code_review
    Exercise:
      title: Exercise
      description: 'An exercise introduces you to, and invites you to complete, a specific activity.'
      type: object
      properties:
        id:
          $ref: '#/components/schemas/id'
        created:
          $ref: '#/components/schemas/timestamp'
        creator:
          $ref: '#/components/schemas/userId'
        promoImage:
          description: File upload. An image used to promote the exercise.
          writeOnly: true
          allOf:
            - $ref: '#/components/schemas/fileUpload'
        displayInfo:
          description: Information related to how the exercise will be displayed.
          type: object
          readOnly: true
          properties:
            promoImage:
              description: An image used to promote the exercise.
              allOf:
                - $ref: '#/components/schemas/url'
        description:
          title: description
          description: A set of expressions combined to form a rich description of the activity requested.
          type: array
          items:
            anyOf:
              - $ref: '#/components/schemas/TextExpression'
              - $ref: '#/components/schemas/MathExpression'
              - $ref: '#/components/schemas/CodeExpression'
              - $ref: '#/components/schemas/ImageExpression'
              - $ref: '#/components/schemas/AudioExpression'
              - $ref: '#/components/schemas/AnimationExpression'
              - $ref: '#/components/schemas/VideoExpression'
        type:
          $ref: '#/components/schemas/ExerciseTypes'
      required:
        - id
        - created
        - description
        - type
    OrganizationType:
      title: type
      description: The type of organization.
      type: string
      enum:
        - company
        - ngo
        - igo
        - non-profit
        - government_department
        - government_agency
    OrganizationBranding:
      title: Organization Branding
      description: The branding associated with the organization.
      properties:
        icon:
          description: An icon for the organization. Must be square and at least 128px x 128px.
          allOf:
            - $ref: '#/components/schemas/File'
            - nullable: true
        logo:
          description: A logo for the organization that will be used in on pages. Must be at least 128px x 128px.
          allOf:
            - $ref: '#/components/schemas/File'
            - nullable: true
        primary_color:
          description: A CSS hex color value representing the primary branding color for this organization.
          nullable: true
          type: string
    Organization:
      title: Organization
      description: 'An organized group of people with a particular purpose, such as a business, government agency, non-profit, etc.'
      type: object
      properties:
        id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/id'
        name:
          description: The name of the orgnization.
          type: string
          example: Sci-Code AS
        organizationNumber:
          title: extra info
          description: 'The number issued by the government, proving that the organization exists.'
          type: string
          example: Sci-Code AS
        visionStatement:
          description: 'A short, descriptive text of what future the organization aims to bring about.'
          type: string
          example: 'Sci-Code, as a company, is actively developing services, tools and technologies that contributes towards closing the gap between industry and education. The motivation and value upon which the Company has been built is usefulness. The key of any country’s societal development is based on Education. It is how a generation of people pass its knowledge, know-how and values to the next one. This is why we''re building a new educational system, pillared on the advances in technology that will enable exploratory learning, personalized learning experiences tailored to each individual, and the most  stimulating education in the world; verified by our algorithms. This system will serve as an alternative to the current education system, allowing for a seamless and gradual, piece-by-piece transition. And through building this new system, we allow for the change of our current societal dogma of school and learning being perceived as necessarily boring and hard, into school and learning being AWESOME.'
        type:
          $ref: '#/components/schemas/OrganizationType'
        organizationBranding:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/OrganizationBranding'
        icon:
          description: File upload. An icon for the organization. Must be square and at least 128px x 128px.
          writeOnly: true
          allOf:
            - $ref: '#/components/schemas/fileUpload'
        logo:
          description: File Upload. A logo for the organization that will be used in on pages. Must be at least 128px x 128px.
          writeOnly: true
          allOf:
            - $ref: '#/components/schemas/fileUpload'
      required:
        - id
        - name
        - type
    Challenge:
      title: Challenge
      description: Basically a set of exercises combined for the purpose of testing skills.
      type: object
      properties:
        id:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/id'
        object:
          title: value is "challenge"
          allOf:
            - $ref: '#/components/schemas/object'
            - pattern: ^challenge$
            - example: challenge
            - readOnly: true
        created:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/timestamp'
        creator:
          readOnly: true
          allOf:
            - $ref: '#/components/schemas/userId'
        title:
          description: A short text describing the challenge.
          type: string
          example: Build your first Form Component
        tagline:
          description: 'A short add-on text, adding more details to the title.'
          type: string
          example: Show your skills in React by building a simple form component
        description:
          description: An ordered list of sections describing the challenge.
          type: array
          items:
            title: Challenge Description Section
            type: object
            properties:
              headline:
                description: The headline of the section.
                type: string
              bodycopy:
                description: Approximately a paragraph of text describing the section.
                type: string
              label:
                description: A piece of text describing the section.
                type: string
              featuredBlob:
                readOnly: true
                description: 'A featured blob (image, etc.) for the section.'
                allOf:
                  - $ref: '#/components/schemas/url'
              featuredBlobFile:
                writeOnly: true
                description: 'A file containing the featured blob (image, etc.) for the section.'
                allOf:
                  - $ref: '#/components/schemas/fileUpload'
        tags:
          description: A set of keywords related to the challenge.
          type: array
          items:
            type: string
          example:
            - react.js
            - redux.js
        promoImage:
          readOnly: true
          description: A visual description of the challenge.
          allOf:
            - $ref: '#/components/schemas/url'
        promoImageFile:
          writeOnly: true
          description: A file containing the visual description of the challenge.
          allOf:
            - $ref: '#/components/schemas/fileUpload'
        promoVideo:
          readOnly: true
          description: 'An in-depth, stimulating descrpition of the challenge.'
          allOf:
            - $ref: '#/components/schemas/url'
        promoVideoFile:
          writeOnly: true
          description: 'A file containing an in-depth, stimulating descrpition of the challenge.'
          allOf:
            - $ref: '#/components/schemas/fileUpload'
        availabilityRanges:
          description: The durations where people will be able to take the challenge.
          type: array
          items:
            type: object
            properties:
              open_time:
                description: Date and Time when the challenge opens. Measured in seconds since the Unix epoch.
                allOf:
                  - $ref: '#/components/schemas/timestamp'
              close_time:
                description: Date and Time at which the challenge closes. Measured in seconds since the Unix epoch.
                allOf:
                  - $ref: '#/components/schemas/timestamp'
        difficulty:
          description: The difficulty level of the challenge.
          enum:
            - beginner
            - intermediate
            - advanced
          type: string
        langauges:
          description: The supported languages for this challenge.
          type: array
          items:
            $ref: '#/components/schemas/language'
        exercises:
          description: The exercises making up the challenge.
          type: array
          items:
            $ref: '#/components/schemas/Exercise'
          nullable: true
        organizers:
          description: The organization(s) hosting the challenge
          type: array
          items:
            $ref: '#/components/schemas/Organization'
          nullable: true
        published:
          description: 'If the challenge is published, it''ll be listed in the public challenge catalog. If not, only the ones with the right link will be able to access it. This meets the need for recruiters to prevent solicitation of pre-vetted candidates.'
          type: boolean
          default: false
          example: true
  responses:
    400_bad_request:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: There seems to be something wrong with your request.
    401_unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: 'Seems like you aren''t authenticated. Please authenticate yoruself, then try again.'
    403_forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: 'Sorry, you do not have access rights to this content.'
    404_not_found:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Seems like the resource you requested doesn't exist.
    bad_request_400:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: There seems to be something wrong with your request.
    unauthorized_401:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: 'Seems like you aren''t authenticated. Please authenticate yoruself, then try again.'
    forbidden_403:
      description: Forbidden
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: 'Sorry, you do not have access rights to this content.'
    not_found_404:
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                example: Seems like the resource you requested doesn't exist.
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: diggit.eu.auth0.com
          scopes:
            'write:challenges': create or update challenges