mcserver_api.yaml

openapi: "3.0.0"

info:
  title: Machina Callida Backend REST API
  version: "1.0"
servers:
  - url: http://localhost:5000/mc/api/v1.0

paths:
  /corpora:
    get:
      summary: Returns a list of corpora.
      operationId: mcserver.app.api.corpusListAPI.get
      responses:
        200:
          description: Corpus list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
      parameters:
        - name: last_update_time
          in: query
          description: Time (in milliseconds) of the last update.
          required: true
          schema:
            type: integer
            example: 123456789
  /corpora/{cid}:
    parameters:
      - name: cid
        in: path
        description: Corpus identifier.
        required: true
        schema:
          type: integer
          example: 1
    delete:
      summary: Deletes a single corpus by ID.
      operationId: mcserver.app.api.corpusAPI.delete
      responses:
        200:
          description: Indication of success
          content:
            application/json:
              schema:
                type: boolean
                example: true
    get:
      summary: Returns a single corpus by ID.
      operationId: mcserver.app.api.corpusAPI.get
      responses:
        200:
          description: Corpus object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
    patch:
      summary: Updates a single corpus by ID.
      operationId: mcserver.app.api.corpusAPI.patch
      responses:
        200:
          description: Corpus object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
      parameters:
        - name: author
          in: query
          description: Author of the texts in the corpus.
          required: false
          schema:
            type: string
            example: Aulus Gellius
        - name: source_urn
          in: query
          description: CTS base URN for referencing the corpus.
          required: false
          schema:
            type: string
            example: urn:cts:latinLit:phi1254.phi001.perseus-lat2
        - name: title
          in: query
          description: Corpus title.
          required: false
          schema:
            type: string
            example: Noctes Atticae
  /exercise:
    get:
      summary: Returns exercise data by ID.
      operationId: mcserver.app.api.exerciseAPI.get
      responses:
        200:
          description: Exercise data object
      #          TODO: SPECIFY RESPONSE SCHEMA
      parameters:
        - name: eid
          in: query
          description: Unique identifier (UUID) for the exercise.
          required: true
          schema:
            type: string
            example: 12345678-1234-5678-1234-567812345678
    post:
      summary: Creates a new exercise.
      operationId: mcserver.app.api.exerciseAPI.post
      responses:
        200:
          description: Exercise data object
      #          TODO: SPECIFY RESPONSE SCHEMA
      requestBody:
        $ref: '#/components/requestBodies/ExerciseForm'
components:
  requestBodies:
    ExerciseForm:
      required: true
      content:
        application/x-www-form-urlencoded:
          schema:
            x-body-name: exercise_data
            type: object
            allOf:
              - $ref: '#/components/schemas/ExerciseBase'
                required:
                  - instructions
                  - search_values
              - description: Additional exercise data.
                type: object
                properties:
                  type:
                    type: string
                    description: Type of exercise, concerning interaction and layout.
                    example: markWords
                  type_translation:
                    type: string
                    description: Localized expression of the exercise type.
                    example: Cloze
                  urn:
                    type: string
                    description: CTS URN for the text passage from which the exercise was created.
                    example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1
                required:
                  - type
  schemas:
    Corpus:  # Object definition
      description: Collection of texts.
      type: object   # Data type
      x-tablename: Corpus
      properties:
        author:
          type: string
          description: Author of the texts in the corpus.
          example: Aulus Gellius
          default: "Anonymus"
          nullable: false
        cid:
          type: integer
          description: Unique identifier for the corpus.
          example: 1
          x-primary-key: true
          x-autoincrement: true
        citation_level_1:
          type: string
          description: First level for citing the corpus.
          example: Book
          default: default
        citation_level_2:
          type: string
          description: Second level for citing the corpus.
          example: Chapter
          default: default
        citation_level_3:
          type: string
          description: Third level for citing the corpus.
          example: Section
          default: default
        source_urn:
          type: string
          description: CTS base URN for referencing the corpus.
          example: urn:cts:latinLit:phi1254.phi001.perseus-lat2
          x-unique: true
        title:
          type: string
          description: Corpus title.
          example: Noctes Atticae
          nullable: false
          default: Anonymus
      required:
        - source_urn
    Exercise:
      allOf:
        - $ref: "#/components/schemas/ExerciseBase"
        - description: Data for creating and evaluating interactive exercises.
          type: object   # Data type
          x-tablename: Exercise
          properties:
            conll:
              type: string
              description: CONLL-formatted linguistic annotations represented as a single string.
              example: \# newdoc id = ...\n# sent_id = 1\n# text = Caesar fortis est.\n1\tCaesar\tCaeso\tVERB ...
              default: ""
              nullable: false
            eid:
              type: string
              description: Unique identifier (UUID) for the exercise.
              example: 12345678-1234-5678-1234-567812345678
              x-primary-key: true
            exercise_type:
              type: string
              description: Type of exercise, concerning interaction and layout.
              example: markWords
              default: ""
              nullable: false
            exercise_type_translation:
              type: string
              description: Localized expression of the exercise type.
              example: Cloze
              default: ""
            language:
              type: string
              description: ISO 639-1 Language Code for the localization of exercise content.
              example: en
              default: de
            last_access_time:
              type: number
              format: float
              description: When the exercise was last accessed (as POSIX timestamp).
              example: 1234567.789
              x-index: true
            solutions:
              type: string
              description: Correct solutions for the exercise.
              example: "[{'target': {'sentence_id': 1, 'token_id': 7, 'salt_id': 'salt:/urn:...', 'content': 'eo'}, 'value': {'sentence_id': 0, 'token_id': 0, 'content': None, 'salt_id': 'salt:/urn:...'}}]"
              default: "[]"
              nullable: false
            text_complexity:
              type: number
              format: float
              description: Overall text complexity as measured by the software's internal language analysis.
              example: 54.53
              default: 0
            urn:
              type: string
              description: CTS URN for the text passage from which the exercise was created.
              example: urn:cts:latinLit:phi0448.phi001.perseus-lat2:1.1.1
              default: ""
              nullable: false
          required:
            - eid
            - last_access_time
    LearningResult:
      description: Learner data for completed exercises.
      type: object
      x-tablename: LearningResult
      properties:
        actor_account_name:
          type: string
          description: H5P user ID, usually unique per device.
          example: ebea3f3e-7410-4215-b34d-c1417f7c7c18
          default: ""
        actor_object_type:
          type: string
          description: Describes the kind of object that was recognized as actor.
          example: Agent
          default: ""
        category_id:
          type: string
          description: Link to the exercise type specification.
          example: http://h5p.org/libraries/H5P.MarkTheWords-1.9
          default: ""
        category_object_type:
          type: string
          description: Describes the kind of object that was recognized as exercise.
          example: Activity
          default: ""
        choices:
          type: string
          description: JSON string containing a list of possible choices, each with ID and description.
          example: "[{'id':'2','description':{'en-US':'Quintus ist bei allen in der Provinz beliebt.\n'}},{'id':'3','description':{'en-US':'Asia ist eine unbekannte Provinz.\n'}}]"
          default: "[]"
        completion:
          type: boolean
          description: Whether the exercise was fully processed or not.
          example: true
        correct_responses_pattern:
          type: string
          description: JSON string containing a list of possible solutions to the exercise, given as patterns of answers.
          example: "['0[,]1[,]2']"
        created_time:
          type: number
          format: float
          description: When the learner data was received (POSIX timestamp).
          example: 1234567.789
          x-index: true
          x-primary-key: true
        duration:
          type: string
          description: How many seconds it took a learner to complete the exercise.
          example: PT9.19S
          default: "PT0S"
        extensions:
          type: string
          description: JSON string containing a mapping of keys and values (usually the local content ID, i.e. a versioning mechanism).
          example: "{'http://h5p.org/x-api/h5p-local-content-id':1}"
          default: "{}"
        interaction_type:
          type: string
          description: Exercise type.
          example: choice
          default: ""
        object_definition_description:
          type: string
          description: Exercise content, possibly including instructions.
          example: "Bestimme die Form von custodem im Satz: Urbs custodem non tyrannum, domus hospitem non expilatorem recepit.\n"
        object_definition_type:
          type: string
          description: Type of object definition that is presented to the user.
          example: http://adlnet.gov/expapi/activities/cmi.interaction
          default: ""
        object_object_type:
          type: string
          description: Type of object that is presented to the user.
          example: Activity
          default: ""
        response:
          type: string
          description: Answer provided by the user, possibly as a pattern.
          example: His in rebus[,]sociis[,]civibus[,]rei publicae
        score_max:
          type: integer
          description: Maximum possible score to be achieved in this exercise.
          example: 1
        score_min:
          type: integer
          description: Minimum score to be achieved in this exercise.
          example: 0
        score_raw:
          type: integer
          description: Score that was actually achieved by the user in this exercise.
          example: 1
        score_scaled:
          type: number
          format: float
          description: Relative score (between 0 and 1) that was actually achieved by the user in this exercise.
          example: 0.8889
          default: 0
        success:
          type: boolean
          description: Whether the exercise was successfully completed or not.
          example: true
        verb_display:
          type: string
          description: Type of action that was performed by the user.
          example: answered
          default: ""
        verb_id:
          type: string
          description: Link to the type of action that was performed by the user.
          example: http://adlnet.gov/expapi/verbs/answered
          default: ""
      required:
        - completion
        - correct_responses_pattern
        - created_time
        - object_definition_description
        - response
        - score_max
        - score_min
        - score_raw
        - success
    UpdateInfo:
      description: Timestamps for updates of various resources.
      type: object
      x-tablename: UpdateInfo
      properties:
        created_time:
          type: number
          format: float
          description: When the resource was created (as POSIX timestamp).
          example: 1234567.789
          x-index: true
        last_modified_time:
          type: number
          format: float
          description: When the resource was last modified (as POSIX timestamp).
          example: 1234567.789
          x-index: true
        resource_type:
          type: string
          enum: [cts_data, exercise_list, file_api_clean]
          description: Name of the resource for which update timestamps are indexed.
          example: cts_data
          x-primary-key: true
      required:
        - created_time
        - last_modified_time
        - resource_type
    ExerciseBase:
      description: Base data for creating and evaluating interactive exercises.
      type: object
      properties:
        correct_feedback:
          type: string
          description: Feedback for successful completion of the exercise.
          example: Well done!
          default: ""
        general_feedback:
          type: string
          description: Feedback for finishing the exercise.
          example: You have finished the exercise.
          default: ""
        incorrect_feedback:
          type: string
          description: Feedback for failing to complete the exercise successfully.
          example: Unfortunately, that answer is wrong.
          default: ""
        instructions:
          type: string
          description: Hints for how to complete the exercise.
          example: Fill in the gaps!
          default: ""
        partially_correct_feedback:
          type: string
          description: Feedback for successfully completing certain parts of the exercise.
          example: Some parts of this answer are correct.
          default: ""
        search_values:
          type: string
          description: Search queries that were used to build the exercise.
          example: "['upostag=noun', 'dependency=object']"
          default: "[]"
        work_author:
          type: string
          description: Name of the person who wrote the base text for the exercise.
          example: C. Iulius Caesar
          default: ""
        work_title:
          type: string
          description: Title of the base text for the exercise.
          example: Noctes Atticae
          default: ""