{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "QTI item API"
    },
    "tags": [
        {
            "name": "item",
            "description": "Operations about items"
        }
    ],
    "paths": {
        "/taoQtiItem/RestQtiItem/export/": {
            "get": {
                "description": "Exports an existing QTI Item as a QTI 2.1 package",
                "tags": [
                    "item"
                ],
                "produces": [
                    "application/json",
                    "application/zip"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "description": "Item id in URI format",
                        "required": true,
                        "type": "string",
                        "format": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response return QTI zip package content",
                        "schema": {
                            "type": "file",
                            "format": "application/zip"
                        }
                    },
                    "400": {
                        "description": "Bad request if you send invalid parameters",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "required parameter `id` is missing",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "User isn't authorized to access to this functionality"
                    },
                    "404": {
                        "description": "Item not found",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "Item can't be found",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "500": {
                        "description": "Internal error (should not occur)"
                    }
                }
            }
        },
        "/taoQtiItem/RestQtiItem/import/": {
            "post": {
                "description": "Import QTI item entry point from uploaded package Check POST method & get valid uploaded file",
                "tags": [
                    "item"
                ],
                "parameters": [
                    {
                        "name": "content",
                        "in": "formData",
                        "description": "file attachemnt zip format supported",
                        "required": true,
                        "type": "file"
                    },
                    {
                        "name": "class-uri",
                        "in": "formData",
                        "description": "Class uri to import item. If not specified root class will be used.",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "class-label",
                        "in": "formData",
                        "description": "Label of class to import item. If not specified root class will be used. If label is not unique first match will be used.",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "enableMetadataGuardians",
                        "in": "formData",
                        "description": "Boolean flag that indicates to use or not metadata guardians during the import. If parameter not specified, metadata guardians will be used by default.",
                        "type": "boolean",
                        "required": false
                    },
                    {
                        "name": "enableMetadataValidators",
                        "in": "formData",
                        "description": "Boolean flag that indicates to use or not metadata validators during the import. If parameter not specified, metadata guardians will be used by default.",
                        "type": "boolean",
                        "required": false
                    },
                    {
                        "name": "itemMustExist",
                        "in": "formData",
                        "description": "Boolean flag that indicates whether items must be found by one metadata guardian. In case of the item is not found by a metadata guardian, the import will fail. Default value is false.",
                        "type": "boolean",
                        "required": false
                    },
                    {
                        "name": "itemMustBeOverwritten",
                        "in": "formData",
                        "description": "Boolean flag that indicates whether items found by guardians should be overwritten. Default value is false.",
                        "type": "boolean",
                        "required": false
                    }
                ],
                "consumes": [
                    "multipart/form-data"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "schema": {
                            "title": "response",
                            "format": "json",
                            "type": "object",
                            "required": [
                                "success",
                                "version"
                            ],
                            "properties": {
                                "success": {
                                    "type": "boolean",
                                    "description": "false on failure, true on success"
                                },
                                "version": {
                                    "type": "string",
                                    "description": "tao version"
                                },
                                "data": {
                                    "$ref": "#/definitions/data"
                                },
                                "errorCode": {
                                    "type": "string",
                                    "description": "error code. it appear if success value is false"
                                },
                                "errorMsg": {
                                    "type": "string",
                                    "description": "error description. it appear if success value is false"
                                }
                            }
                        },
                        "examples": {
                            "application/json": {
                                "success": true,
                                "data": {
                                    "items": [
                                        "http://tao.local/mytao.rdf#xxxxxxxxxxxxx1",
                                        "http://tao.local/mytao.rdf#xxxxxxxxxxxxx2",
                                        "http://tao.local/mytao.rdf#xxxxxxxxxxxxx3",
                                        "http://tao.local/mytao.rdf#xxxxxxxxxxxxx4"
                                    ]
                                },
                                "version": "3.1.0"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request if you send invalid parameters",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "At least one mandatory parameter was required but found missing in your request",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "User isn't authorized to access to this functionality"
                    },
                    "500": {
                        "description": "Internal error (should not occur)"
                    }
                }
            }
        },
        "/taoQtiItem/RestQtiItem/importDeferred/": {
            "post": {
                "description": "Asynchronous import QTI item entry point from uploaded package Check POST method & get valid uploaded file",
                "tags": [
                    "item"
                ],
                "parameters": [
                    {
                        "name": "content",
                        "in": "formData",
                        "description": "file attachemnt zip format supported",
                        "required": true,
                        "type": "file"
                    },
                    {
                        "name": "class-uri",
                        "in": "formData",
                        "description": "Class uri to import item. If not specified root class will be used.",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "class-label",
                        "in": "formData",
                        "description": "Label of class to import item. If not specified root class will be used. If label is not unique first match will be used.",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "enableMetadataGuardians",
                        "in": "formData",
                        "description": "Boolean flag that indicates to use or not metadata guardians during the import. If parameter not specified, metadata guardians will be used by default.",
                        "type": "boolean",
                        "required": false
                    },
                    {
                        "name": "enableMetadataValidators",
                        "in": "formData",
                        "description": "Boolean flag that indicates to use or not metadata validators during the import. If parameter not specified, metadata guardians will be used by default.",
                        "type": "boolean",
                        "required": false
                    },
                    {
                        "name": "itemMustExist",
                        "in": "formData",
                        "description": "Boolean flag that indicates whether items must be found by one metadata guardian. In case of the item is not found by a metadata guardian, the import will fail. Default value is false.",
                        "type": "boolean",
                        "required": false
                    },
                    {
                        "name": "itemMustBeOverwritten",
                        "in": "formData",
                        "description": "Boolean flag that indicates whether items found by guardians should be overwritten. Default value is false.",
                        "type": "boolean",
                        "required": false
                    }
                ],
                "consumes": [
                    "multipart/form-data"
                ],
                "responses": {
                    "200": {
                        "description": "Request was correctly handled, task to import item was created",
                        "schema": {
                            "title": "response",
                            "format": "json",
                            "type": "object",
                            "required": [
                                "success",
                                "version",
                                "data"
                            ],
                            "properties": {
                                "success": {
                                    "type": "boolean",
                                    "description": "True on success"
                                },
                                "version": {
                                    "type": "string",
                                    "description": "Tao version"
                                },
                                "data": {
                                    "type": "object",
                                    "properties": {
                                        "reference_id": {
                                            "type": "string",
                                            "description": "Identifier of the task in the task queue"
                                        },
                                        "report": {
                                            "type": "object",
                                            "description": "Report on importing. This field is presented only if queueing was not used",
                                            "properties": {
                                                "type": {
                                                    "type": "string"
                                                },
                                                "message": {
                                                    "type": "string"
                                                },
                                                "children": {
                                                    "type": "array",
                                                    "items": {
                                                        "type": "object"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        },
                        "examples": {
                            "application/json": {
                                "success": true,
                                "data": {
                                    "reference_id": "http://tao.local/mytao.rdf#xxxxxxxxxxxxx",
                                    "report": {
                                        "type": "info",
                                        "message": "Running task http://tao.local/mytao.rdf#xxxxxxxxxxxxx",
                                        "data": null,
                                        "children": [
                                            {
                                                "type": "success",
                                                "message": "1 Item(s) of 1 imported from the given IMS QTI Package.",
                                                "data": null,
                                                "children": [
                                                    {
                                                        "type": "success",
                                                        "message": "The IMS QTI Item referenced as \"xxxxxxxxxxxxx\" in the IMS Manifest file was successfully imported.",
                                                        "data": {
                                                            "uriResource": "http://tao.local/mytao.rdf#xxxxxxxxxxxxx",
                                                            "label": "Planets and moons",
                                                            "comment": ""
                                                        },
                                                        "children": []
                                                    }
                                                ]
                                            }
                                        ]
                                    }
                                },
                                "version": "3.2.0"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request if you send invalid parameters",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "At least one mandatory parameter was required but found missing in your request",
                                "version": "3.2.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "User isn't authorized to access to this functionality"
                    },
                    "500": {
                        "description": "Internal error (should not occur)"
                    }
                }
            }
        },
        "/taoQtiItem/RestQtiItem/getStatus": {
            "get": {
                "description": "Check status of import item package task. Available since Tao 3.2",
                "tags": [
                    "item"
                ],
                "responses": {
                    "200": {
                        "description": "Request was correctly handled, task found",
                        "schema": {
                            "title": "response",
                            "format": "json",
                            "type": "object",
                            "required": [
                                "success",
                                "version",
                                "data"
                            ],
                            "properties": {
                                "success": {
                                    "type": "boolean",
                                    "description": "True on success"
                                },
                                "version": {
                                    "type": "string",
                                    "description": "Tao version"
                                },
                                "data": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "description": "Task execution status"
                                        },
                                        "itemIds": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            },
                                            "description": "List of identifiers of imported items"
                                        },
                                        "id": {
                                            "type": "string",
                                            "description": "task ID in URI format"
                                        },
                                        "report": {
                                            "type": "array",
                                            "items": {
                                                "type": "object",
                                                "properties": {
                                                    "type": {
                                                        "type": "string"
                                                    },
                                                    "message": {
                                                        "type": "string"
                                                    }
                                                }
                                            }
                                        }
                                    }
                                }
                            }
                        },
                        "examples": {
                            "application/json": {
                                "success": true,
                                "data": {
                                    "status": "Success",
                                    "itemIds": [
                                        "http://tao.local/mytao.rdf#xxxxxxxxxxxxx"
                                    ],
                                    "id": "http://tao.local/mytao.rdf#xxxxxxxxxxxxx",
                                    "report": [
                                        {
                                            "type": "info",
                                            "message": "Running task http://tao.local/mytao.rdf#xxxxxxxxxxxxx"
                                        },
                                        {
                                            "type": "success",
                                            "message": "1 Item(s) of 1 imported from the given IMS QTI Package."
                                        },
                                        {
                                            "type": "success",
                                            "message": "The IMS QTI Item referenced as \"xxxxxxxxxxxxx\" in the IMS Manifest file was successfully imported."
                                        }
                                    ]
                                },
                                "version": "3.2.0"
                            }
                        }
                    },
                    "404": {
                        "description": "Task with given id was not found"
                    },
                    "500": {
                        "description": "Internal error (should not occur)"
                    }
                },
                "parameters": [
                    {
                        "name": "id",
                        "in": "query",
                        "description": "job reference",
                        "type": "string",
                        "required": true
                    }
                ],
                "consumes": [
                    "application/x-www-form-urlencoded"
                ]
            }
        },
        "/taoQtiItem/RestQtiItem/createQtiItem/": {
            "post": {
                "description": "Create an empty QTI item",
                "tags": [
                    "item"
                ],
                "parameters": [
                    {
                        "name": "label",
                        "in": "formData",
                        "description": "Item Label",
                        "required": true,
                        "type": "string",
                        "format": "string"
                    },
                    {
                        "name": "class-uri",
                        "in": "formData",
                        "description": "Class uri to import item. If not specified root class will be used.",
                        "type": "string",
                        "required": false
                    },
                    {
                        "name": "class-label",
                        "in": "formData",
                        "description": "Label of class to import item. If not specified root class will be used. If label is not unique first match will be used.",
                        "type": "string",
                        "required": false
                    }
                ],
                "consumes": [
                    "multipart/form-data"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "examples": {
                            "application/json": {
                                "success": true,
                                "data": "http://tao.local/mytao.rdf#xxxxxxxxxxxxx",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "title": "response",
                            "format": "json",
                            "type": "object",
                            "required": [
                                "success",
                                "version",
                                "data"
                            ],
                            "properties": {
                                "success": {
                                    "type": "boolean",
                                    "description": "true on success"
                                },
                                "version": {
                                    "type": "string"
                                },
                                "data": {
                                    "type": "string",
                                    "description": "item uri"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request if you send invalid parameters",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "At least one mandatory parameter was required but found missing in your request",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "401": {
                        "description": "Unauthorized"
                    },
                    "403": {
                        "description": "User isn't authorized to access to this functionality"
                    },
                    "500": {
                        "description": "Internal error (should not occur)"
                    }
                }
            }
        },
        "/taoQtiItem/RestQtiItem/createClass": {
            "post": {
                "description": "Create an item class",
                "tags": [
                    "item"
                ],
                "parameters": [
                    {
                        "name": "class-label",
                        "in": "formData",
                        "description": "Item class label to create",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "parent-class-uri",
                        "in": "formData",
                        "description": "Parent item class uri. If not specified or not exists then root item class will be used",
                        "required": false,
                        "type": "string"
                    },
                    {
                        "name": "class-comment",
                        "in": "formData",
                        "description": "The comment of new created class",
                        "required": false,
                        "type": "string"
                    }
                ],
                "consumes": [
                    "multipart/form-data"
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "schema": {
                            "title": "response",
                            "format": "json",
                            "type": "object",
                            "required": [
                                "success",
                                "version"
                            ],
                            "properties": {
                                "success": {
                                    "type": "boolean",
                                    "description": "false on failure, true on success"
                                },
                                "version": {
                                    "type": "string",
                                    "description": "tao version"
                                },
                                "data": {
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "description": "A message to explain if class is newly created or it already exists"
                                        },
                                        "class-uri": {
                                            "type": "string",
                                            "description": "The uri of newly created item class"
                                        }
                                    }
                                },
                                "errorCode": {
                                    "type": "string",
                                    "description": "error code. it appear if success value is false"
                                },
                                "errorMsg": {
                                    "type": "string",
                                    "description": "error description. it appear if success value is false"
                                }
                            }
                        },
                        "examples": {
                            "application/json": {
                                "success": true,
                                "data": {
                                    "message": "Class successfully created.",
                                    "class-uri": "http://tao.local/mytao.rdf#xxxxxxxxxxxxx"
                                },
                                "version": "3.1.0"
                            }
                        }
                    },
                    "400": {
                        "description": "Bad request if you send invalid parameters. class-label uri is mandatory.",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "At least one mandatory parameter was required but found missing in your request",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "You don't have permission to access this resource.",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "500": {
                        "description": "Internal error, if class-parent-uri is not a valid item class.",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "Exception error description",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    }
                }
            }
        },
        "/taoQtiItem/RestQtiItem/updateMetadata": {
            "post": {
                "description": "Update the metadata of a given item",
                "tags": [
                    "item"
                ],
                "parameters": [
                    {
                        "name": "body",
                        "in": "body",
                        "description": "The metadata that has to be updated",
                        "required": true,
                        "schema": {
                            "$ref": "#/definitions/metadataEntity"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "schema": {
                            "$ref": "#/definitions/updateMetadataResponse"
                        }
                    },
                    "400": {
                        "description": "Bad request if you send invalid parameters.",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "At least one mandatory parameter was required but found missing in your request",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "401": {
                        "description": "Unauthorized",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "You don't have permission to access this resource.",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    },
                    "500": {
                        "description": "Internal error",
                        "examples": {
                            "application/json": {
                                "success": false,
                                "errorCode": 0,
                                "errorMsg": "Exception error description",
                                "version": "3.1.0"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/errorModel"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "errorModel": {
            "type": "object",
            "description": "contain error",
            "required": [
                "success",
                "version",
                "errorCode",
                "errorMsg"
            ],
            "properties": {
                "success": {
                    "type": "boolean",
                    "description": "false on failure",
                    "default": false
                },
                "version": {
                    "type": "string",
                    "description": "tao version"
                },
                "errorCode": {
                    "type": "integer",
                    "description": "error code"
                },
                "errorMsg": {
                    "type": "string",
                    "description": "error description"
                }
            }
        },
        "data": {
            "type": "object",
            "description": "output user data, it appear if success value is true",
            "properties": {
                "items": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            }
        },
        "metadataEntity": {
            "type": "object",
            "required": [
                "resourceUri",
                "propertyUri",
                "value"
            ],
            "properties": {
                "resourceUri": {
                    "type": "string",
                    "description": "The Item URI where the Metadata Belongs to",
                    "example": "https://tao.local/ontologies/tao.rdf#my-item-uri"
                },
                "propertyUri": {
                    "type": "string",
                    "description": "The Property URI where the Metadata value is related",
                    "example": "https://tao.local/ontologies/tao.rdf#my-property-uri"
                },
                "value": {
                    "type": "string",
                    "description": "The value of the metadata",
                    "example": "This is a metadata update"
                }
            }
        },
        "updateMetadataResponse": {
            "type": "array",
            "items": {
                "type": "object",
                "required": [
                    "success",
                    "data"
                ],
                "properties": {
                    "success": {
                        "type": "boolean"
                    },
                    "data": {
                        "$ref": "#/definitions/metadataEntity"
                    }
                }
            }
        }
    },
    "externalDocs": {
        "description": "taoQtiItem on Github",
        "url": "https://github.com/oat-sa/extension-tao-itemqti"
    }
}