swagger.json

{
  "swagger": "2.0",
  "info": {
    "title": "Course memo/Kurs-PM API",
    "description": "Api to store information about uploaded course memos to be used in course development and course info projects",
    "version": "1.0.0"
  },
  "basePath": "/api/kurs-pm",
  "produces": ["application/json"],
  "paths": {
    "/_checkAPIkey": {
      "get": {
        "tags": ["system"],
        "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/courseMemoData/{id}": {
      "get": {
        "operationId": "getCourseMemoDataById",
        "summary": "Get course memo document descriptive data by document unique id ",
        "description": "Gets some form of data that only requires read access",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Id of the round.semester.year.x to course memo data",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "The requested data",
            "schema": {
              "$ref": "#/definitions/MemoData"
            }
          },
          "401": {
            "description": "This endpoint is secured - **credentials are missing or invalid**."
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["read"]
          }
        ]
      },
      "post": {
        "operationId": "postCourseMemoData",
        "summary": "Saves an object of one course memo document descriptive data in the database per course and term",
        "description": "Saves a course memo document descriptive data in the database per course and term",
        "parameters": [
          {
            "name": "roundCourseMemoData",
            "in": "body",
            "description": "Array with memo data objects",
            "required": true,
            "schema": {
              "$ref": "#/definitions/MemoData"
            }
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "A successful save"
          },
          "401": {
            "description": "This endpoint is secured - **credentials are missing or invalid**."
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["write"]
          }
        ]
      },
      "put": {
        "operationId": "putCourseMemoDataById",
        "summary": "Update an existing object in the database",
        "description": "Update an existing object in the database",
        "parameters": [
          {
            "name": "roundCourseMemoData",
            "in": "body",
            "description": "Course Memo Data for specific term and course round",
            "schema": {
              "$ref": "#/definitions/MemoData"
            }
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "A successful update"
          },
          "401": {
            "description": "This endpoint is secured - **credentials are missing or invalid**."
          },
          "default": {
            "description": "Unexpected error",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          }
        },
        "security": [
          {
            "api_key": ["write"]
          }
        ]
      },
      "delete": {
        "operationId": "deleteCourseMemoDataById",
        "summary": "Delete a course memo",
        "description": "Delete all information for course memo with sent id",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Id of the round.semester.year.x to delete course memo data",
            "required": true,
            "type": "string"
          }
        ],
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "The analysis was deleted",
            "schema": {
              "$ref": "#/definitions/MemoData"
            }
          },
          "401": {
            "description": "This endpoint is secured - **credentials are missing or invalid**."
          },
          "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 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"
            }
          },
          "401": {
            "description": "This endpoint is secured - **credentials are missing or invalid**."
          },
          "400": {
            "description": "Bad Request, something with the request is invalid",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          },
          "404": {
            "description": "No organization or user matched the Ids",
            "schema": {
              "$ref": "#/definitions/Error"
            }
          },
          "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": {
    "MemoData": {
      "properties": {
        "_id": {
          "type": "string",
          "description": "Unique identifier representing some specific data"
        },
        "courseCode": {
          "type": "string",
          "description": "Course code for which it is valid"
        },
        "pdfMemoUploadDate": {
          "type": "string",
          "description": "When document were published (first)?? time"
        },
        "changedBy": {
          "type": "string",
          "description": "Unique KTH id of user who uploaded or changed this document data, f.e., u1iooii,"
        },
        "semester": {
          "type": "string",
          "description": "Course start term year (spring(VT)-1, autumn(HT)-2) , f.e. 20182 or 20181 (termin)"
        },
        "courseMemoFileName": {
          "type": "string",
          "description": "Uploaded courseMemo file"
        },
        "lastChangeDate": {
          "type": "string",
          "description": "Date and time for last change, set by API"
        },
        "previousFileList": {
          "type": "array",
          "items": "object",
          "description": "Array for object with previous memo files and its upload date",
          "properties": {
            "courseMemoFileName": {
              "type": "string",
              "description": "File name of a previous course memo"
            },
            "lastChangeDate": {
              "type": "string",
              "description": "Published date of a previous course memo"
            },
            "version": {
              "type": "string",
              "description": "Version number of course memo"
            }
          }
        }
      }
    },
    "MemoDataListForCourseCode": {
      "properties": {
        "_id": {
          "type": "string",
          "description": "Unique identifier representing some specific data"
        },
        "courseCode": {
          "type": "string",
          "description": "Course code for which it is valid"
        },
        "pdfMemoUploadDate": {
          "type": "string",
          "description": "When document were published (first)?? time"
        },
        "courseMemoFileName": {
          "type": "string",
          "description": "Uploaded courseMemo file"
        },
        "changedAfterPublishedDate": {
          "type": "string",
          "description": "Date for changes made after published???"
        }
      }
    },
    "UsedRoundsForCourseAndSemester": {
      "memoList": {
        "type": "string",
        "description": "Who made changes to documents"
      }
    },
    "Error": {
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "fields": {
          "type": "string"
        }
      }
    },
    "UserList": {
      "properties": {
        "code": {
          "type": "integer",
          "format": "int32"
        },
        "message": {
          "type": "string"
        },
        "fields": {
          "type": "string"
        }
      }
    }
  }
}