swagger.yaml

swagger: '2.0'

info:
  version: '1.0'
  title: "knodels"
  description: API for managing a homework system.

#Basic security through authentication
securityDefinitions:
  ApiToken:
    type: apiKey
    in: header
    name: API-Key
    
security:
  - ApiToken: []

host: knodels.herokuapp.com

basePath: /v1

schemes:
- https

consumes:
- application/json
produces:
- application/json
    
definitions:

  User:
    type: object
    required:
      - UserId
    properties:
      UserId:
        type: string
        description: 'Id of the user'
        example: 5c0d49861c9d440000d55486
    $ref: "#/definitions/UserData"
  
  UserData:
    type: object
    properties:
      Name:
        type: string
        description: 'Full name of the user'
        example: 'Mario'
      Surname:
        type: string
        description: 'Full surname of the user'
        example: 'Rossi'
      Email:
        type: string
        description: 'User''s email'
        example: 'mario.rossi@knodel.it'
    required:
    - Name
    - Surname
    - Email
  UserDataArray:
    type: array
    items:
      $ref: '#/definitions/UserData'
    example: [
               {
                  "name": "Emiliano",
                 "surname": "Andreotti",
                 "email": "emiliano.andreotti@mailservice.com"
                },
                {
                  "name": "Luca",
                  "surname": "Gagliardi",
                  "email": "luca.gagliardi@mailservice.com"
                 },
                {
                  "name": "John",
                  "surname": "Treppendorf",
                  "email": "john.treppendorf@mailservice.com"
                }
             ]
  CreateUserResponse:
    type: array
    items:
      type: object
  Task:
    allOf:
    - type: object
      properties:
        TaskId:
          type: integer
          format: int64
          description: The number that identifies a single task
          example: 235
      required:
      - TaskId
    - $ref: "#/definitions/TaskData"
    
      
  TaskData:
    title: TaskData
    description: Object storing tasks data
    type: object
    properties:
      TaskType:
        type: string
        description: The type of the task
        example: multichoice
      Question:
        type: string
        description: The full question
        example: What's your name?
      Options:
        type: array
        description: Possible answers
        items:
          type: string
          description: option
      Answers:
        type: array
        description: Right answers
        items:
          type: string
          description: answer
      TaskFile:
        type: string
        #apiary doesn't support binary format
        #format: binary
        description: The file attached to the task
    required:
      - Question
      - TaskType
      - TaskFile
  
  WorkGroup:
    title: WorkGroup
    description: A set of users that are tasked to complete together an exam assigned to them
    type: array
    items:
      type: integer
      description: the id of a user
    
  Exam:
    allOf:
    - type: object
      properties:
        ExamId:
          type: integer
          format: int64
          description: The number that identifies a single exam
          example: 245
      required:
      - ExamId
    - $ref: "#/definitions/ExamData"
          
  ExamData:
    title: ExamData
    description: All the informations about an exam
    type: object
    properties:
      Name:
        type: string
        description: A user friendly name fot the exam
        example: formal languages and compilers
      Description:
        type: string
        description: A short description of the exam
        example: The exam consists of 13 question, the first 5 are about formal languages, the 7 laters are open questions about compilers and their algorithms. The last one is the bonus question.
      Deadline:
        type: integer
        format: int64
        description: The date in which the exam must be completed, using Unix time.
        example: 1550676600
      WorkGroups:
        type: array
        description: The groups the exam is assigned for
        items:
          $ref: "#/definitions/WorkGroup"
      Tasks:
        type: array
        description: The list of tasks to complete for the exam
        items:
          type: integer
          description: the id of a task
    required:
      - Name
      - Description
      - Deadline
      - Tasks

  Submission:
    allOf:
    - type: object
      properties:
        SubmissionId:
          type: integer
          format: int64
          description: The hexadecimal number that identifies a submission
          example: 5c0c385783d3885536cca830
      required:
      - SubmissionId
    - $ref: "#/definitions/SubmissionData"
          
  SubmissionData:
    title: SubmissionData
    description: All the informations about a submission
    type: object
    properties:
      Exam:
          type: integer
          format: int64
          description: The number that identifies a single exam
          example: 245
      WorkGroup:
        type: object
        description: The group that made the submission
        $ref: "#/definitions/WorkGroup"
      Answers:
        type: array
        description: The list of the answers
        items:
          type: string
          description: The written answer for a question
    required:
      - Exam
      - WorkGroup
      - Answers
      
responses:
  InvalidDataError:
    description: The request contains invalid data
  DataNotFoundError:
    description: The data requested hadn't been found
  UnauthorizedError:
    description: Authentication information is missing or invalid
  ConflictError:
    description: The submitted data is conflicting
paths:

  /login/:
    post:
      parameters:
      - in: body
        name: UserLoginData
        description: The login data of the user
        schema:
          type: object
          properties:
            UserEmail:
              type: string
              description: The email used during the sign up
              example: mario.rossi@knodel.it
            UserPassword:
              type: string
              description: The password chosen during the sign up
              example: P455w0Rd
      summary: Authentication of the user
      security: [] #No security for login
      tags: [Login]
      responses:
        200:
          description: ok
          schema:
            type: object
            properties:
              ApiKey:
                type: string
                description: The key for authentication
            required:
            - ApiKey
        400:
          description: The email or the password are not valid
          
  /logout/:
    get:
      summary: Dismiss authentication of the user
      security: [] #No security for logout
      tags: [Logout]
      responses:
        204:
          description: No Content, succesful response without return any content
        400:
          description: Bad Request, if the user aren't authenticated
        
  /users:
    get:
      summary: Get all users
      description: Retrieve the complete list of users
      tags: [Users]
      responses:
        200:
          description: ok
          schema:
            type: array
            items:
              $ref: "#/definitions/UserDataArray"
    post:
      tags: [User]
      description: >-
        Creates new users in the system (one or many)
      summary: Create new users
      parameters: 
      - in: body
        name: user
        required: true
        schema:
          type: object
          $ref: "#/definitions/UserDataArray"
      responses:
        201:
          description: 'Ids of created users'
          
        400:
          description: 'Bad request'
        404:
          description: 'Data not found'
  /users/{UserId}:
    parameters:
      - in: path
        name: UserId
        required: true
        type: string
        description: A 24 characters long string in hex format
    get:
      summary: Get a user
      description: Retrieve the informations of the user identified by the specific id
      tags: [Users]
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/UserData"
        400:
          description: Bad Request
        404:
          description: Data not found
          $ref: "#/responses/DataNotFoundError"
    put:
      summary: Update a user
      description: Modify one or more attributes of a specific user
      tags: [Users]
      parameters:
      - in: body
        name: user
        required: true
        schema:
           $ref: "#/definitions/UserData"
      responses:
        201:
          description: User successfully modified
        400:
          description: Bad request
          $ref: "#/responses/DataNotFoundError"
        404:
          description: Data not found
    delete:
      summary: Delete a user
      description: Delete a specific user
      tags: [Users]
      responses:
        200:
          description: User successfully deleted
        400:
          description: Bad request
          $ref: "#/responses/DataNotFoundError"
        404:
          description: Data not found

  /users/{UserId}/submissions/:
    parameters:
      - in: path
        name: UserId
        required: true
        type: integer
    get:
      summary: Get a user's submission
      description: Retrieve the submissions of the user identified by the specific id
      tags: [Submissions]
      responses:
        200:
          description: ok
          schema:
            type: array
            items:
              $ref: "#/definitions/Submission"
        404:
          $ref: "#/responses/DataNotFoundError"
  
  /tasks/:
    get:
      summary: Retrieve all the tasks in the system
      
      parameters:
        - in: query
          name: offset
          type: integer
          minimum: 0
          description: The number of tasks to skip
        - in: query
          name: limit
          type: integer
          minimum: 0
          description: The number of tasks to display
          
      tags: [Tasks]
      responses:
        200:
          description: ok
          schema:
            type: array
            items:
              $ref: "#/definitions/Task"
        400:
          description: Bad Request
        404:
          $ref: "#/responses/DataNotFoundError"
    post:
      summary: Create a new task
      tags: [Tasks]
      parameters:
      - in: body
        name: task
        schema:
          $ref: "#/definitions/TaskData"
      responses:
        201:
          description: The task has been successfully created
        400:
          $ref: "#/responses/InvalidDataError"
  
  /tasks/{TaskId}/:
    parameters:
      - in: path
        name: TaskId
        required: true
        type: integer
    get:
      summary: Retrieve the information about the task with the specific TaskId
      tags: [Tasks]
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/Task"
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"
    put:
      summary: Modify task informations
      tags: [Tasks]
      parameters:
      - in: body
        name: task
        required: true
        schema:
           $ref: "#/definitions/TaskData"
      responses:
        200:
          description: Task successfully modified
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"
    delete:
      summary: Remove the task identified with TaskId from the system
      tags: [Tasks]
      responses:
        200:
          description: The task has been successfully deleted
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"

  /exams/:
    get:
      summary: Retrieve all the exams
      
      parameters:
        - in: query
          name: offset
          type: integer
          minimum: 0
          description: The number of exams to skip
        - in: query
          name: limit
          type: integer
          minimum: 0
          description: The number of exams to display
          
      tags: [Exams]
      responses:
        200:
          description: Succesful request
          schema:
            type: array
            items:
              $ref: "#/definitions/ExamData"
        400:
          description: Bad Request, wrong parameters |
                       Bad Request, invalid parameter |
                       Bad Request, wrong number of parameters
    post:
      summary: Create a new exam
      tags: [Exams]
      parameters:
      - in: body
        name: exam
        schema: 
          $ref: "#/definitions/ExamData"
      responses:
        201:
          description: The exam has been successfully created
        400:
          $ref: "#/responses/InvalidDataError"
          
  /exams/{ExamId}/:
    parameters:
      - in: path
        name: ExamId
        required: true
        type: integer
    get:
      summary: Retrieve the information about an exam
      tags: [Exams]
      responses:
        200:
          description: Succesful request
          schema:
            $ref: "#/definitions/ExamData"
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"
    put:
      summary: Modify exam informations
      tags: [Exams]
      parameters:
      - in: body
        name: exam
        required: true
        schema:
           $ref: "#/definitions/ExamData"
      responses:
        200:
          description: Exam successfully update
          schema:
            $ref: "#/definitions/ExamData"
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"
    delete:
      summary: Delete an exam
      tags: [Exams]
      responses:
        200:
          description: The exam has been successfully deleted
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"

  /exams/{ExamId}/submissions/:
    parameters:
      - in: path
        name: ExamId
        required: true
        type: integer
    get:
      summary: Retrieve the submissions related to the exam identified by the specific id
      tags: [Submissions]
      responses:
        200:
          description: ok
          schema:
            type: array
            items:
              $ref: "#/definitions/Submission"
        404:
          $ref: "#/responses/DataNotFoundError"
          
  /submissions/:
    get:
      summary: Retrieve all the submissions
      
      parameters:
        - in: query
          name: offset
          type: integer
          minimum: 0
          description: The number of submissions to skip
        - in: query
          name: limit
          type: integer
          minimum: 0
          description: The number of submissions to display
          
      tags: [Submissions]
      responses:
        200:
          description: ok
          schema:
            type: array
            items:
              $ref: "#/definitions/Submission"
        404:
          $ref: "#/responses/DataNotFoundError"
    post:
      summary: Make a submission
      tags: [Submissions]
      parameters:
      - in: body
        name: submission
        schema: 
          $ref: "#/definitions/SubmissionData"
      responses:
        201:
          description: The submission has been done
        400:
          $ref: "#/responses/InvalidDataError"
          
  /submissions/{SubmissionId}/:
    parameters:
      - in: path
        name: SubmissionId
        required: true
        type: integer
    get:
      summary: Retrieve the information about a submission
      tags: [Submissions]
      responses:
        200:
          description: ok
          schema:
            $ref: "#/definitions/Submission"
        404:
          $ref: "#/responses/DataNotFoundError"
    put:
      summary: Modifies the information about an existing submission
      tags: [Submissions]
      parameters:
      - in: body
        name: submission
        required: true
        schema:
           $ref: "#/definitions/SubmissionData"
      responses:
        204:
          description: ok, submission successfully modified
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"
          
    delete:
      summary: Delete a submission
      tags: [Submissions]
      responses:
        200:
          description: The submission has been successfully deleted
        400:
          $ref: "#/responses/InvalidDataError"
        404:
          $ref: "#/responses/DataNotFoundError"
          
  /submissions/{SubmissionId}/evaluation/:
    post:
      summary: Give a mark and a commet to a submission
      tags: [evaluation]
      parameters:
      - in: path
        name: SubmissionId
        required: true
        type: integer
      - in: body
        name: EvaluationData
        description: Evaluation gived by a TA to a submission
        schema:
          type: object
          properties:
            Mark:
              type: number
              format: float
              description: Mark assign to a submission
              example: 7.8
            Comment:
              type: string
              description: Comment left to a submission
      responses:
        200:
          description: Action completed succesfully
        400:
          description: Bad Request