swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "Kursutveckling API",
    "description": "Used to collect and show course analysis with some course data",
    "version": "1.0.0"
  },
  "basePath": "/api/kursutveckling",
  "produces": ["application/json"],
  "paths": {
    "/_checkAPIkey": {
      "get": {
        "operationId": "checkAPIkey",
        "summary": "Test authentication setup",
        "description": "Secured test endpoint which can be used to validate that a client has a working authentication setup\n\n_(System.checkAPIKey)_",
        "parameters": [],
        "responses": {
          "200": {
            "description": "The given authentication is **accepted**"
          },
          "401": {
            "description": "This endpoint is secured - **credentials are missing or invalid**."
          },
          "default": {
            "description": "Unexpected response - internal error"
          }
        },
        "security": [{ "api_key": ["read"] }]
      }
    },
    "/v1/courseRoundAnalysis/{id}": {
      "get": {
        "operationId": "getCourseRoundAnalysisDataById",
        "summary": "Get a list of all analysis connected to a course code",
        "description": "Get a list of all analysis connected to a course code",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Course Round Analysis Id (Course Code + Semester + _ + Round Id(s)",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "List of analyses for course code and all the data",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      },
      "post": {
        "operationId": "postCourseRoundAnalysisDataById",
        "summary": "Saves an analysis object in the database",
        "description": "Saves an analysis object in the database",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Course Round Analysis Id (Course Code + Semester + _ + Round Id(s)",
            "required": true,
            "type": "string"
          },
          {
            "name": "roundAnalysisData",
            "in": "body",
            "description": "Analysis data  ",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "A successful save"
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["write"]
          }
        ]
      },
      "put": {
        "operationId": "putCourseRoundAnalysisDataById",
        "summary": "Updates an analysis",
        "description": "Saves changes to an analysis in the database",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Course Round Analysis Id (Course Code + Semester + _ + Round Id(s)",
            "required": true,
            "type": "string"
          },
          {
            "name": "roundAnalysisData",
            "in": "body",
            "description": "Analysis data for a course round(s) round ",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "A successful update"
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["write"]
          }
        ]
      },
      "delete": {
        "operationId": "deleteCourseRoundAnalysisDataById",
        "summary": "Delete an analysis",
        "description": "Delete all information for analysis with sent id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Id of the round.semester.year.x to delete analysis data",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "The analysis was deleted",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      }
    },
    "/v1/usedRoundsForCourse/{courseCode}/semester/{semester}": {
      "get": {
        "operationId": "getUsedRounds",
        "summary": "Gets a list of used round ids for a semester in a course",
        "parameters": [
          {
            "name": "courseCode",
            "in": "path",
            "description": "Course code, six or seven characters",
            "required": true,
            "type": "string"
          },
          {
            "name": "semester",
            "description": "Semester for rounds",
            "in": "path",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "Round ids",
            "schema": {
              "$ref": "#/definitions/UsedRoundsForCourseAndSemester"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      }
    },
    "/v1/courseAnalysisList/{courseCode}/{semester}": {
      "get": {
        "operationId": "getAnalysisListByCourseCode",
        "summary": "Get a list of analyses for a course",
        "description": "Gets analyses for rounds in a course",
        "parameters": [
          {
            "name": "courseCode",
            "in": "path",
            "description": "Id of the course code",
            "required": true,
            "type": "string"
          },
          {
            "name": "semester",
            "in": "path",
            "description": "Semester code, five numbers as a string (year + 1 (spring) or 2 (fall). Filter results for that semester",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "Successfully got analyses for requested course code and semester",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      }
    },
    "/v1/courseAnalyses/{semester}": {
      "get": {
        "operationId": "getCourseAnalysesForSemester",
        "summary": "Get a list of published analyses for a semester",
        "description": "Gets all published analyses for rounds in a semester",
        "parameters": [
          {
            "name": "semester",
            "in": "path",
            "description": "Semester code, five numbers as a string (year + 1 (spring) or 2 (fall). Filter results for that semester",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "Successfully got published analyses for requested semester",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      }
    },
    "/v1/courseAnalysesForSemestersList": {
      "get": {
        "operationId": "getCourseAnalysesForSemestersList",
        "summary": "Get a list of published analyses for a list of semesters",
        "description": "Gets all published analyses for rounds for all semesters provided in query ?semesters=20212,29222",
        "parameters": [
          {
            "name": "semester",
            "in": "query",
            "description": "Semesters codes, each semester code is five numbers as a string (year + 1 (spring) or 2 (fall). Filter results for these semesters",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "Successfully got published analyses for requested semesters",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      }
    },
    "/v1/canvasCourseAnalysisList/{courseCode}": {
      "get": {
        "operationId": "getCanvasAnalysisListByCourseCode",
        "summary": "Get a list of analyses for a course",
        "description": "Get a list of analyses for a course round published in Canvas",
        "parameters": [
          {
            "name": "courseCode",
            "in": "path",
            "description": "Id of the course code",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "Successfully got analyses for requested course code",
            "schema": {
              "$ref": "#/definitions/RoundAnalysisCanvas"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      }
    },
    "/v1/adminWebCourseAnalysisList/{courseCode}": {
      "get": {
        "operationId": "getAdminWebAnalysisListByCourseCode",
        "summary": "Get a list of analyses for a course",
        "description": "Get a list of analyses for a course round published in the old analysis admin tool \"Kursanalys och kursdata\" previously found in kursutveckling-admin-web.",
        "parameters": [
          {
            "name": "courseCode",
            "in": "path",
            "description": "Id of the course code",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "Successfully got analyses for requested course code",
            "schema": {
              "$ref": "#/definitions/RoundAnalysis"
            }
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      }
    }
  },
  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "name": "api_key",
      "in": "header",
      "scopes": {
        "read": "Read access to data",
        "write": "Write access to data"
      }
    }
  },
  "definitions": {
    "RoundAnalysis": {
      "type": "object",
      "required": ["courseCode"],
      "properties": {
        "analysisName": {
          "type": "string",
          "description": "Analysis name"
        },
        "courseCode": {
          "type": "string",
          "description": "Coure code for the course that are connected to the analysis"
        },
        "programmeCodes": {
          "type": "string",
          "description": "Programmes that are mandatory"
        },
        "examiners": {
          "type": "string",
          "description": "Examiner(s) for the course that semester"
        },
        "responsibles": {
          "type": "string",
          "description": "Responsible(s) for the course that semester"
        },
        "examinationRounds": {
          "type": "string",
          "description": "Examinations rounds for the course and semester"
        },
        "registeredStudents": {
          "type": "string",
          "description": "Number of registere student for round(s) that semester"
        },
        "examinationGrade": {
          "type": "string",
          "description": "Precentage of students completed the round(s)"
        },
        "endDate": {
          "type": "string",
          "description": "End date for round(s) that semester"
        },
        "alterationText": {
          "type": "string",
          "description": "Text that descibes changes that have been made in the course"
        },
        "commentExam": {
          "type": "string",
          "description": "Comment to Examination round(s)"
        },
        "commentChange": {
          "type": "string",
          "description": "Mandatory text if changes are made after analysis been published"
        },
        "isPublished": {
          "type": "string",
          "description": "Sets to true when analysis is published"
        },
        "publishedDate": {
          "type": "string",
          "description": "Date when analysis is first published"
        },
        "pdfAnalysisDate": {
          "type": "string",
          "description": "Date when analysis file was uploaded"
        },
        "changedDate": {
          "type": "string",
          "description": "Date when an analysis was updated"
        },
        "changedBy": {
          "type": "string",
          "description": "Username of creator of the analysis"
        },
        "semester": {
          "type": "string",
          "description": "Course semester for analysis"
        },
        "applicationCodes": {
          "type": "string",
          "description": "Application code(s) used in analysis"
        },
        "analysisFileName": {
          "type": "string",
          "description": "Name of uploaded analysis file"
        },
        "ugKeys": {
          "type": "array",
          "items": { "type": "string" },
          "description": "UG Keys for user access to edit analysis"
        },
        "syllabusStartTerm": {
          "type": "string",
          "description": "Connected syllabus"
        },
        "changedAfterPublishedDate": {
          "type": "string",
          "description": "Date for changes made after published"
        },
        "examinationGradeFromLadok": {
          "type": "boolean",
          "description": "A check if values been collected from Ladok or filled in by user"
        },
        "registeredStudentsFromLadok": {
          "type": "boolean",
          "description": "A check if values been collected from Ladok or filled in by user"
        },
        "registeredStudentsLadok": {
          "type": "integer",
          "description": "The result of registered students that was collected from Ladok "
        },
        "examinationGradeLadok": {
          "type": "integer",
          "description": "The result of examination grade that was collected from Ladok "
        },
        "endDateFromLadok": {
          "type": "boolean",
          "description": "A check if values been collected from Ladok or filled in by user"
        },
        "endDateLadok": {
          "type": "string",
          "description": "The end date used for result of examination grade that was collected from Ladok "
        },
        "ladokUIDs": {
          "type": "array",
          "description": "The UIDs collected from Ladok",
          "items": { "type": "string" }
        }
      },
      "example": {
        "_id": "XYZ123VT2021_1",
        "alterationText": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras cursus vel urna vel scelerisque. Integer erat risus, rutrum vitae vestibulum et, condimentum vitae nisl.",
        "analysisFileName": "analysis-XYZ123VT2021-1-20210601-00-01.pdf",
        "analysisName": "XYZ ( Startdatum 2021-02-01, Svenska ) ",
        "changedAfterPublishedDate": "",
        "changedBy": "xyz",
        "changedDate": "2021-06-01T00:01:01.001Z",
        "commentChange": "",
        "commentExam": "<p>Duis neque neque, vestibulum a erat non, viverra posuere dui. Maecenas quis nunc non turpis luctus fringilla. Integer dui est, sodales sit amet dapibus dictum, luctus non purus. Etiam vestibulum tincidunt nulla et blandit.<br />In pellentesque velit at finibus vulputate. Quisque feugiat interdum nulla.</p>",
        "courseCode": "XYZ123",
        "endDate": "2021-05-01",
        "endDateFromLadok": true,
        "endDateLadok": "2021-05-01",
        "examinationGrade": "99.0",
        "examinationGradeFromLadok": true,
        "examinationGradeLadok": 99,
        "examinationRounds": "",
        "examiners": "xyz",
        "isPublished": "true",
        "ladokUIDs": ["aa485652-148f-11ec-82a8-0242ac130003"],
        "programmeCodes": "XYZ",
        "pdfAnalysisDate": "2021-06-01",
        "publishedDate": "2021-06-01T01:01:01.001Z",
        "responsibles": "xyz",
        "registeredStudents": "xyz",
        "registeredStudentsFromLadok": true,
        "registeredStudentsLadok": 100,
        "applicationCodes": "1",
        "semester": "20211",
        "syllabusStartTerm": "20211",
        "ugKeys": ["XYZ123.examiner", "XYZ123.20211.1.courseresponsible"]
      }
    },
    "RoundAnalysisCanvas": {
      "type": "object",
      "required": ["courseCode"],
      "properties": {
        "alterationText": {
          "type": "string",
          "description": "Text that describes changes that have been made in the course"
        },
        "analysisName": {
          "type": "string",
          "description": "Analysis name"
        },
        "applicationCodes": {
          "type": "string",
          "description": "Application code(s) used in analysis"
        },
        "courseCode": {
          "type": "string",
          "description": "Course code for the course that is connected to the analysis"
        },
        "endDate": {
          "type": "string",
          "description": "End date for round(s) that semester"
        },
        "examinationRounds": {
          "type": "string",
          "description": "Examinations rounds for the course and semester"
        },
        "examiners": {
          "type": "string",
          "description": "Examiner(s) for the course that semester"
        },
        "gradingDistribution": {
          "type": "object",
          "description": "Grading distribution for reported results"
        },
        "id": {
          "type": "string",
          "description": "Id for round analysis. Same as ladokUID."
        },
        "ladokUIDs": {
          "type": "array",
          "description": "The UIDs collected from Ladok",
          "items": { "type": "string" }
        },
        "programmeCodes": {
          "type": "string",
          "description": "Programmes that are mandatory"
        },
        "registeredStudents": {
          "type": "string",
          "description": "Number of registered students for round(s) that semester"
        },
        "responsibles": {
          "type": "string",
          "description": "Responsible(s) for the course that semester"
        },
        "semester": {
          "type": "string",
          "description": "Course semester for analysis"
        },
        "startDate": {
          "type": "string",
          "description": "Start date for round(s) that semester"
        },
        "totalReportedResults": {
          "type": "string",
          "description": "Number of total reported results"
        }
      },
      "example": {
        "_id": "ObjectId(6711178a1353f5e3af556077)",
        "alterationText": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Cras cursus vel urna vel scelerisque. Integer erat risus, rutrum vitae vestibulum et, condimentum vitae nisl.",
        "analysisName": "XYZ ( Startdatum 2021-02-01, Svenska ) ",
        "applicationCodes": "1, 2, 3",
        "courseCode": "XYZ123",
        "endDate": "2021-05-01",
        "examinationRounds": "",
        "examiners": "xyz",
        "gradingDistribution": {
          "A": 0,
          "B": 0,
          "C": 0,
          "D": 0,
          "E": 0,
          "FX": 0,
          "F": 0
        },
        "id": "aa485652-148f-11ec-82a8-0242ac130003",
        "ladokUIDs": ["aa485652-148f-11ec-82a8-0242ac130003"],
        "programmeCodes": "XYZ",
        "registeredStudents": "2",
        "responsibles": "xyz",
        "semester": "20211",
        "startDate": "2021-02-01",
        "totalReportedResults": "0"
      }
    },
    "UsedRoundsForCourseAndSemester": {
      "properties": {
        "usedRounds": {
          "type": "array",
          "items": { "type": "string" },
          "description": "List of round ids that have been used for a course semester"
        },
        "publishedAnalysis": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "schema": {
                "$ref": "#/definitions/UsedAnalysis"
              }
            }
          },
          "description": "List of published analysis, name, id, UGkeys"
        },
        "draftAnalysis": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "schema": {
                "$ref": "#/definitions/UsedAnalysis"
              }
            }
          },
          "description": "List of draft analysis, name, id, UGkeys"
        }
      }
    },
    "UsedAnalysis": {
      "properties": {
        "user": {
          "type": "string"
        },
        "isPublished": {
          "type": "boolean"
        },
        "analysisId": {
          "type": "string"
        },
        "analysisName": {
          "type": "string"
        },
        "ugKeys": {
          "type": "array",
          "items": { "type": "string" }
        }
      }
    },
    "Error": {
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "fields": {
          "type": "string"
        }
      }
    }
  }
}