diff --git a/.gitignore b/.gitignore index 36bf2307e..728ccc53f 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ data/* openml_OS/config/BASE_CONFIG.php openml_OS/third_party/OpenML/Java/old-evaluate.jar docs/site/ +openml_OS/vendor/ +openapi/vendor/ \ No newline at end of file diff --git a/openapi/README.md b/openapi/README.md new file mode 100644 index 000000000..85f6b44c7 --- /dev/null +++ b/openapi/README.md @@ -0,0 +1,62 @@ +# OpenAPI REST API Documentation + +In order to facilitate interfacing with OpenML's REST API, it is desribed by means of OpenAPI. +However, in order to ensure that the specification is up-to-date with the current code base and the documentation does not need to be duplicated (once in the OpenAPI specification file and once in-line in the code base), in-line annotations are leveraged to facilitate the maintenance of the documentation. Via the composer package [zircote/swagger-php](https://zircote.github.io/swagger-php/), the annotations are compiled into an OpenAPI specification file (either yaml or json). Instructions on how to freshly generate the OpenAPI specification from the current code base as well as how to create/edit documentation for the REST API is given in the following. + +## Getting Started + +Prerequisite: In order to generate the up-to-date OpenAPI specification according to the current code base, you need to have the php-cli package installed on your device. + +For compiling in-line documentation into an OpenAPI specification file, the zircote/swagger-php package is used. This tool will allow you to search the entire code base and distill an OpenAPI specification from all found in-line comments. + +* Open a terminal and change into the `openapi/` directory. +* Install the zircote/swagger-php package by running the command `php composer.phar install` + +Now you have everything in place to start compiling an OpenAPI specification file from the code base. + +## Generate OpenML's Current OpenAPI Specification + +For generating OpenML's up-to-date OpenAPI specification, depending on your operating system, you may choose one of the scripts contained in the `openapi/` directory. +For all operating systems, there are two flavors of the script: one producing a yaml file and one a json file. The contents of both files will be the same except for the format itself. + +If you are a Linux of MacOS user, you may use the .sh-Scripts: + +``` +./generate_json_api.sh # This will compile the OpenAPI specification in JSON format. +./generate_yaml_api.sh # This will compile the OpenAPI specification in YAML format. +``` + +As a Windows user, you may want to use the following batch scripts: + +``` +./generate_json_api.bat # This will compile the OpenAPI specification in JSON format. +./generate_yaml_api.bat # This will compile the OpenAPI specification in YAML format. +``` + +## Instructions for the In-Line Documentation +The inline annotations for PHP work similar as in Java, following the schema @(). In case of the OpenAPI annotations the most important components such as the annotations for get, post, or put methods have distinct annotations. However, all OpenAPI specific annotations are namespaced with an `OA\`. Thus the annotation for get, post, and put correspond to `@OA\Get(...)`, `@OA\Post(...)`, and `@OA\Put(...)` respectively. The information about the path, tags, description, parameters, etc. is then enclosed within the parantheses. While keys such as path, tags, description, and so on which only take a simple value (instead of a complex object) are directly referenced, parameters for instance are specified with the help of distinct annotations again, i.e. `@OA\Parameter(...)`. + +A more comprehensive description of what kind of annotations are supported by the OpenAPI specification and more details on the PHP annotations please refer to the official [OpenAPI specification website](https://swagger.io/specification/) or the [zircote/swagger-php project page](https://zircote.github.io/swagger-php/). + +### Important Notice for Arrays + +Pay attention when specifying arrays within the PHP-Annotations. Brackets ([]) are not supported by the zircote/swagger-php compiler and need to be replaced by curly brackets ({}). It may seem to be a little awkward in the beginning, but eventually it works out. + +Example: Instead of specifying an object like +``` +{ + "a": [ 0, 1, 2 ] +} +``` +write +``` +{ + "a": { 0, 1, 2 } +} +``` +instead. + + +### Unused Schemas + +Schemas describe return types of the REST API. Since they can be nested into each other it is not always easy to see which of them are no longer needed. In order to identify orphan schemas, you can run the `unusedSchemas.py` Python script. The script will load the OpenAPI specification located in the current directory and check which schemas are indeed used and which are obsolete. Finally, if there are indeed orphan schemas, it will give out a list of schema names which are not referenced by any other schema or REST method. \ No newline at end of file diff --git a/openapi/composer.json b/openapi/composer.json new file mode 100644 index 000000000..2250e5b9a --- /dev/null +++ b/openapi/composer.json @@ -0,0 +1,14 @@ +{ + "description": "OpenML OpenAPI Specification", + "name": "openml/openapi", + "type": "project", + "homepage": "https://openml.org", + "license": "", + "support": { + "source": "https://github.com/openml/OpenML" + }, + "require": { + "php": ">=5.2.4", + "zircote/swagger-php": "^3.0" + } +} diff --git a/openapi/composer.lock b/openapi/composer.lock new file mode 100644 index 000000000..60b54f452 --- /dev/null +++ b/openapi/composer.lock @@ -0,0 +1,377 @@ +{ + "_readme": [ + "This file locks the dependencies of your project to a known state", + "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", + "This file is @generated automatically" + ], + "content-hash": "57a385db00a99dcd2f118bc72879de3b", + "packages": [ + { + "name": "doctrine/annotations", + "version": "v1.8.0", + "source": { + "type": "git", + "url": "https://github.com/doctrine/annotations.git", + "reference": "904dca4eb10715b92569fbcd79e201d5c349b6bc" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/doctrine/annotations/zipball/904dca4eb10715b92569fbcd79e201d5c349b6bc", + "reference": "904dca4eb10715b92569fbcd79e201d5c349b6bc", + "shasum": "" + }, + "require": { + "doctrine/lexer": "1.*", + "php": "^7.1" + }, + "require-dev": { + "doctrine/cache": "1.*", + "phpunit/phpunit": "^7.5" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "1.7.x-dev" + } + }, + "autoload": { + "psr-4": { + "Doctrine\\Common\\Annotations\\": "lib/Doctrine/Common/Annotations" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Guilherme Blanco", + "email": "guilhermeblanco@gmail.com" + }, + { + "name": "Roman Borschel", + "email": "roman@code-factory.org" + }, + { + "name": "Benjamin Eberlei", + "email": "kontakt@beberlei.de" + }, + { + "name": "Jonathan Wage", + "email": "jonwage@gmail.com" + }, + { + "name": "Johannes Schmitt", + "email": "schmittjoh@gmail.com" + } + ], + "description": "Docblock Annotations Parser", + "homepage": "http://www.doctrine-project.org", + "keywords": [ + "annotations", + "docblock", + "parser" + ], + "time": "2019-10-01T18:55:10+00:00" + }, + { + "name": "doctrine/lexer", + "version": "1.0.2", + "source": { + "type": "git", + "url": "https://github.com/doctrine/lexer.git", + "reference": "1febd6c3ef84253d7c815bed85fc622ad207a9f8" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/doctrine/lexer/zipball/1febd6c3ef84253d7c815bed85fc622ad207a9f8", + "reference": "1febd6c3ef84253d7c815bed85fc622ad207a9f8", + "shasum": "" + }, + "require": { + "php": ">=5.3.2" + }, + "require-dev": { + "phpunit/phpunit": "^4.5" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "1.0.x-dev" + } + }, + "autoload": { + "psr-4": { + "Doctrine\\Common\\Lexer\\": "lib/Doctrine/Common/Lexer" + } + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Roman Borschel", + "email": "roman@code-factory.org" + }, + { + "name": "Guilherme Blanco", + "email": "guilhermeblanco@gmail.com" + }, + { + "name": "Johannes Schmitt", + "email": "schmittjoh@gmail.com" + } + ], + "description": "PHP Doctrine Lexer parser library that can be used in Top-Down, Recursive Descent Parsers.", + "homepage": "https://www.doctrine-project.org/projects/lexer.html", + "keywords": [ + "annotations", + "docblock", + "lexer", + "parser", + "php" + ], + "time": "2019-06-08T11:03:04+00:00" + }, + { + "name": "symfony/finder", + "version": "v4.3.5", + "source": { + "type": "git", + "url": "https://github.com/symfony/finder.git", + "reference": "5e575faa95548d0586f6bedaeabec259714e44d1" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/symfony/finder/zipball/5e575faa95548d0586f6bedaeabec259714e44d1", + "reference": "5e575faa95548d0586f6bedaeabec259714e44d1", + "shasum": "" + }, + "require": { + "php": "^7.1.3" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "4.3-dev" + } + }, + "autoload": { + "psr-4": { + "Symfony\\Component\\Finder\\": "" + }, + "exclude-from-classmap": [ + "/Tests/" + ] + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Fabien Potencier", + "email": "fabien@symfony.com" + }, + { + "name": "Symfony Community", + "homepage": "https://symfony.com/contributors" + } + ], + "description": "Symfony Finder Component", + "homepage": "https://symfony.com", + "time": "2019-09-16T11:29:48+00:00" + }, + { + "name": "symfony/polyfill-ctype", + "version": "v1.12.0", + "source": { + "type": "git", + "url": "https://github.com/symfony/polyfill-ctype.git", + "reference": "550ebaac289296ce228a706d0867afc34687e3f4" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/symfony/polyfill-ctype/zipball/550ebaac289296ce228a706d0867afc34687e3f4", + "reference": "550ebaac289296ce228a706d0867afc34687e3f4", + "shasum": "" + }, + "require": { + "php": ">=5.3.3" + }, + "suggest": { + "ext-ctype": "For best performance" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "1.12-dev" + } + }, + "autoload": { + "psr-4": { + "Symfony\\Polyfill\\Ctype\\": "" + }, + "files": [ + "bootstrap.php" + ] + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Gert de Pagter", + "email": "BackEndTea@gmail.com" + }, + { + "name": "Symfony Community", + "homepage": "https://symfony.com/contributors" + } + ], + "description": "Symfony polyfill for ctype functions", + "homepage": "https://symfony.com", + "keywords": [ + "compatibility", + "ctype", + "polyfill", + "portable" + ], + "time": "2019-08-06T08:03:45+00:00" + }, + { + "name": "symfony/yaml", + "version": "v4.3.5", + "source": { + "type": "git", + "url": "https://github.com/symfony/yaml.git", + "reference": "41e16350a2a1c7383c4735aa2f9fce74cf3d1178" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/symfony/yaml/zipball/41e16350a2a1c7383c4735aa2f9fce74cf3d1178", + "reference": "41e16350a2a1c7383c4735aa2f9fce74cf3d1178", + "shasum": "" + }, + "require": { + "php": "^7.1.3", + "symfony/polyfill-ctype": "~1.8" + }, + "conflict": { + "symfony/console": "<3.4" + }, + "require-dev": { + "symfony/console": "~3.4|~4.0" + }, + "suggest": { + "symfony/console": "For validating YAML files using the lint command" + }, + "type": "library", + "extra": { + "branch-alias": { + "dev-master": "4.3-dev" + } + }, + "autoload": { + "psr-4": { + "Symfony\\Component\\Yaml\\": "" + }, + "exclude-from-classmap": [ + "/Tests/" + ] + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "MIT" + ], + "authors": [ + { + "name": "Fabien Potencier", + "email": "fabien@symfony.com" + }, + { + "name": "Symfony Community", + "homepage": "https://symfony.com/contributors" + } + ], + "description": "Symfony Yaml Component", + "homepage": "https://symfony.com", + "time": "2019-09-11T15:41:19+00:00" + }, + { + "name": "zircote/swagger-php", + "version": "3.0.2", + "source": { + "type": "git", + "url": "https://github.com/zircote/swagger-php.git", + "reference": "f10ab7f81d89dba97653a980cc90cf4b7b73f543" + }, + "dist": { + "type": "zip", + "url": "https://api.github.com/repos/zircote/swagger-php/zipball/f10ab7f81d89dba97653a980cc90cf4b7b73f543", + "reference": "f10ab7f81d89dba97653a980cc90cf4b7b73f543", + "shasum": "" + }, + "require": { + "doctrine/annotations": "*", + "php": ">=7.0", + "symfony/finder": ">=2.2", + "symfony/yaml": ">=3.3" + }, + "require-dev": { + "phpunit/phpunit": ">=6.3", + "squizlabs/php_codesniffer": ">=3.3", + "zendframework/zend-form": "<2.8" + }, + "bin": [ + "bin/openapi" + ], + "type": "library", + "autoload": { + "psr-4": { + "OpenApi\\": "src" + }, + "files": [ + "src/functions.php" + ] + }, + "notification-url": "https://packagist.org/downloads/", + "license": [ + "Apache-2.0" + ], + "authors": [ + { + "name": "Robert Allen", + "email": "zircote@gmail.com", + "homepage": "http://www.zircote.com" + }, + { + "name": "Bob Fanger", + "email": "bfanger@gmail.com", + "homepage": "http://bfanger.nl" + } + ], + "description": "swagger-php - Generate interactive documentation for your RESTful API using phpdoc annotations", + "homepage": "https://github.com/zircote/swagger-php/", + "keywords": [ + "api", + "json", + "rest", + "service discovery" + ], + "time": "2018-11-16T15:04:29+00:00" + } + ], + "packages-dev": [ ], + "aliases": [], + "minimum-stability": "stable", + "stability-flags": [], + "prefer-stable": false, + "prefer-lowest": false, + "platform": { + "php": ">=5.2.4" + }, + "platform-dev": [] +} diff --git a/openapi/composer.phar b/openapi/composer.phar new file mode 100644 index 000000000..89920d398 Binary files /dev/null and b/openapi/composer.phar differ diff --git a/openapi/generate_json_api.bat b/openapi/generate_json_api.bat new file mode 100644 index 000000000..87426a95c --- /dev/null +++ b/openapi/generate_json_api.bat @@ -0,0 +1 @@ +.\vendor\bin\openapi -o swagger.json --format json -e vendor -e libraries ..\openml_OS \ No newline at end of file diff --git a/openapi/generate_json_api.sh b/openapi/generate_json_api.sh new file mode 100644 index 000000000..0b651d7ed --- /dev/null +++ b/openapi/generate_json_api.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +./vendor/bin/openapi -o swagger.json --format json -e vendor -e libraries ../openml_OS \ No newline at end of file diff --git a/openapi/generate_yaml_api.bat b/openapi/generate_yaml_api.bat new file mode 100644 index 000000000..82fb2f145 --- /dev/null +++ b/openapi/generate_yaml_api.bat @@ -0,0 +1 @@ +.\vendor\bin\openapi -o swagger.yaml --format yaml -e vendor -e libraries ..\openml_OS \ No newline at end of file diff --git a/openapi/generate_yaml_api.sh b/openapi/generate_yaml_api.sh new file mode 100644 index 000000000..bd779dd20 --- /dev/null +++ b/openapi/generate_yaml_api.sh @@ -0,0 +1,3 @@ +#!/bin/bash + +./vendor/bin/openapi -o swagger.yaml --format yaml -e vendor -e libraries ../openml_OS \ No newline at end of file diff --git a/openapi/swagger.json b/openapi/swagger.json new file mode 100644 index 000000000..bfb522c48 --- /dev/null +++ b/openapi/swagger.json @@ -0,0 +1,5647 @@ +{ + "openapi": "3.0.0", + "info": { + "title": "OpenML API", + "description": "REST API for sharing, organizing and reusing machine learning datasets, code, and experiments. Follows a predictive URL scheme from endpoint https://www.openml.org/api/v1/json (or /xml). You need to add your api_key for every call except GET calls. The API key can be found in your profile on openml.org.", + "version": "1.0.0" + }, + "servers": [ + { + "url": "https://openml.org/api/v1/json", + "description": "The current OpenML API" + }, + { + "url": "https://test.openml.org/api/v1/json", + "description": "The test OpenML API" + } + ], + "paths": { + "/data/tag": { + "post": { + "tags": [ + "data" + ], + "summary": "Tag a dataset", + "description": "Tags a dataset.", + "operationId": "Api_data::data_tag", + "parameters": [ + { + "name": "data_id", + "in": "query", + "description": "Id of the dataset.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the tagged dataset", + "content": { + "application/json": { + "schema": { + "properties": { + "data_tag": { + "$ref": "#/components/schemas/inline_response_200_2_data_tag" + } + }, + "type": "object" + }, + "example": { + "data_tag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\\n474 - Internal error tagging the entity. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/untag": { + "post": { + "tags": [ + "data" + ], + "summary": "Untag a dataset", + "description": "Untags a dataset.", + "operationId": "Api_data::data_untag", + "parameters": [ + { + "name": "data_id", + "in": "query", + "description": "Id of the dataset.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The ID of the untagged dataset", + "content": { + "application/json": { + "schema": { + "properties": { + "data_untag": { + "$ref": "#/components/schemas/inline_response_200_3_data_untag" + } + }, + "type": "object" + }, + "example": { + "data_untag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\\n479 - Internal error removing the tag. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/list/{filters}": { + "get": { + "tags": [ + "data" + ], + "summary": "List and filter datasets", + "description": "List datasets, possibly filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/data/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all datasets that match the constraints.", + "operationId": "Api_data::data_list", + "parameters": [ + { + "name": "filters", + "in": "path", + "description": "Any combination of these filters\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n /status/{status} - returns only datasets with a given status, either 'active', 'deactivated', or 'in_preparation'.\r\n /tag/{tag} - returns only datasets tagged with the given tag.\r\n /{data_quality}/{range} - returns only tasks for which the underlying datasets have certain qualities. {data_quality} can be data_id, data_name, data_version, number_instances, number_features, number_classes, number_missing_values. {range} can be a specific value or a range in the form 'low..high'. Multiple qualities can be combined, as in 'number_instances/0..50/number_features/0..10'.\r\n ", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of datasets with the given task", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataList" + }, + "example": { + "data": { + "dataset": [ + { + "did": "1", + "name": "anneal", + "status": "active", + "format": "ARFF", + "quality": [ + { + "name": "MajorityClassSize", + "value": "684" + }, + { + "name": "MaxNominalAttDistinctValues", + "value": "10.0" + }, + { + "name": "MinorityClassSize", + "value": "0" + }, + { + "name": "NumBinaryAtts", + "value": "14.0" + }, + { + "name": "NumberOfClasses", + "value": "6" + }, + { + "name": "NumberOfFeatures", + "value": "39" + }, + { + "name": "NumberOfInstances", + "value": "898" + }, + { + "name": "NumberOfInstancesWithMissingValues", + "value": "0" + }, + { + "name": "NumberOfMissingValues", + "value": "0" + }, + { + "name": "NumberOfNumericFeatures", + "value": "6" + }, + { + "name": "NumberOfSymbolicFeatures", + "value": "32" + } + ] + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n370 - Illegal filter specified.\\n371 - Filter values/ranges not properly specified.\\n372 - No results. There where no matches for the given constraints.\\n373 - Can not specify an offset without a limit.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/{id}": { + "get": { + "tags": [ + "data" + ], + "summary": "Get dataset description", + "description": "Returns information about a dataset. The information includes the name, information about the creator, URL to download it and more.", + "operationId": "Api_data::data", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the dataset.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "A dataset description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Data" + }, + "example": { + "data_set_description": { + "id": "1", + "name": "anneal", + "version": "2", + "description": "...", + "format": "ARFF", + "upload_date": "2014-04-06 23:19:20", + "licence": "Public", + "url": "https://www.openml.org/data/download/1/dataset_1_anneal.arff", + "file_id": "1", + "default_target_attribute": "class", + "version_label": "2", + "tag": [ + "study_1", + "uci" + ], + "visibility": "public", + "original_data_url": "https://www.openml.org/d/2", + "status": "active", + "md5_checksum": "d01f6ccd68c88b749b20bbe897de3713" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned\\n110 - Please provide data_id.\\n111 - Unknown dataset. Data set description with data_id was not found in the database.\\n112 - No access granted. This dataset is not shared with you.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "tags": [ + "data" + ], + "summary": "Delete dataset", + "description": "Deletes a dataset. Upon success, it returns the ID of the deleted dataset.", + "operationId": "Api_data::data_delete", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the dataset.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ID of the deleted dataset", + "content": { + "application/json": { + "schema": { + "properties": { + "data_delete": { + "$ref": "#/components/schemas/inline_response_200_data_delete" + } + }, + "type": "object" + }, + "example": { + "data_delete": { + "id": "4328" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned\\n- 350 - Please provide API key. In order to remove your content, please authenticate.\\n- 351 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\\n- 352 - Dataset does not exists. The data ID could not be linked to an existing dataset.\\n- 353 - Dataset is not owned by you. The dataset is owned by another user. Hence you cannot delete it.\\n- 354 - Dataset is in use by other content. Can not be deleted. The data is used in tasks or runs. Delete other content before deleting this dataset.\\n- 355 - Deleting dataset failed. Deleting the dataset failed. Please contact support team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data": { + "post": { + "tags": [ + "data" + ], + "summary": "Upload dataset", + "description": "Uploads a dataset. Upon success, it returns the data id.", + "operationId": "Api_data::data_upload", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/data).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "dataset", + "in": "query", + "description": "The actual dataset, being an ARFF file.", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the uploaded dataset", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_data_set": { + "$ref": "#/components/schemas/inline_response_200_1_upload_data_set" + } + }, + "type": "object" + }, + "example": { + "upload_data_set": { + "id": "4328" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n130 - Problem with file uploading. There was a problem with the file upload.\\n131 - Problem validating uploaded description file. The XML description format does not meet the standards.\\n132 - Failed to move the files. Internal server error, please contact API administrators.\\n133 - Failed to make checksum of datafile. Internal server error, please contact API administrators.\\n134 - Failed to insert record in database. Internal server error, please contact API administrators.\\n135 - Please provide description xml.\\n136 - File failed format verification. The uploaded file is not valid according to the selected file format. Please check the file format specification and try again.\\n137 - Please provide API key. In order to share content, please log in or provide your API key.\\n138 - Authentication failed. The API key was not valid. Please try to login again, or contact API administrators\\n139 - Combination name / version already exists. Leave version out for auto increment\\n140 - Both dataset file and dataset url provided. The system is confused since both a dataset file (post) and a dataset url (xml) are provided. Please remove one.\\n141 - Neither dataset file or dataset url are provided. Please provide either a dataset file as POST variable, or a dataset url in the description XML.\\n142 - Error in processing arff file. Can be a syntax error, or the specified target feature does not exists. For now, we only check on arff files. If a dataset is claimed to be in such a format, and it can not be parsed, this error is returned.\\n143 - Suggested target feature not legal. It is possible to suggest a default target feature (for predictive tasks). However, it should be provided in the data.\\n144 - Unable to update dataset. The dataset with id could not be found in the database. If you upload a new dataset, unset the id.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/status/update/": { + "post": { + "tags": [ + "data" + ], + "summary": "Change the status of a dataset", + "description": "Change the status of a dataset, either 'active' or 'deactivated'", + "operationId": "Api_data::status_update", + "parameters": [ + { + "name": "data_id", + "in": "query", + "description": "Id of the dataset.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "status", + "in": "query", + "description": "The status on which to filter the results, either 'active' or 'deactivated'.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "412": { + "description": "Precondition failed. An error code and message are returned.\\n691 - Illegal status\\n692 - Dataset does not exists\\n693 - Dataset is not owned by you\\n694 - Illegal status transition\\n695 - Status update failed\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/features/{id}": { + "get": { + "tags": [ + "data" + ], + "summary": "Get data features", + "description": "Returns the features of a dataset.", + "operationId": "Api_data::data_features", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the dataset.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "All the features of the dataset", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataFeatures" + }, + "example": { + "data_features": { + "feature": [ + { + "index": "0", + "name": "sepallength", + "data_type": "numeric", + "is_target": "false", + "is_ignore": "false", + "is_row_identifier": "false" + }, + { + "index": "1", + "name": "sepalwidth", + "data_type": "numeric", + "is_target": "false", + "is_ignore": "false", + "is_row_identifier": "false" + }, + { + "index": "2", + "name": "petallength", + "data_type": "numeric", + "is_target": "false", + "is_ignore": "false", + "is_row_identifier": "false" + }, + { + "index": "3", + "name": "petalwidth", + "data_type": "numeric", + "is_target": "false", + "is_ignore": "false", + "is_row_identifier": "false" + }, + { + "index": "4", + "name": "class", + "data_type": "nominal", + "is_target": "true", + "is_ignore": "false", + "is_row_identifier": "false" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n270 - Please provide dataset ID.\\n271 - Unknown dataset. Data set with the given data ID was not found (or is not shared with you).\\n272 - No features found. The dataset did not contain any features, or we could not extract them.\\n273 - Dataset not processed yet. The dataset was not processed yet, features are not yet available. Please wait for a few minutes.\\n274 - Dataset processed with error. The feature extractor has run into an error while processing the dataset. Please check whether it is a valid supported file. If so, please contact the API admins.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/features": { + "post": { + "tags": [ + "data" + ], + "summary": "Upload dataset feature description", + "description": "Uploads dataset feature description. Upon success, it returns the data id.", + "operationId": "Api_data::data_features_upload", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.features) and an [XML example](https://www.openml.org/api/v1/xml_example/data.features).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "412": { + "description": "Precondition failed. An error code and message are returned.\\n431 - Dataset already processed\\n432 - Please provide description xml\\n433 - Problem validating uploaded description file\\n434 - Could not find dataset\\n436 - Something wrong with XML, check data id and evaluation engine id\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/qualities/list": { + "get": { + "tags": [ + "data" + ], + "summary": "List all data qualities", + "description": "Returns a list of all data qualities in the system.", + "operationId": "Api_data::data_qualities_list", + "responses": { + "200": { + "description": "A list of data qualities", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataQualityList" + }, + "example": { + "data_qualities_list": { + "quality": [ + "NumberOfClasses", + "NumberOfFeatures", + "NumberOfInstances", + "NumberOfInstancesWithMissingValues", + "NumberOfMissingValues", + "NumberOfNumericFeatures", + "NumberOfSymbolicFeatures" + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned\\n370 - No data qualities available. There are no data qualities in the system.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/qualities/{id}": { + "get": { + "tags": [ + "data" + ], + "summary": "Get data qualities", + "description": "Returns the qualities of a dataset.", + "operationId": "Api_data::data_qualities", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the dataset.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "All the qualities of the dataset", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataQualities" + }, + "example": { + "data_qualities": { + "quality": [ + { + "name": "ClassCount", + "value": "3.0" + }, + { + "name": "ClassEntropy", + "value": "1.584962500721156" + }, + { + "name": "NumberOfClasses", + "value": "3" + }, + { + "name": "NumberOfFeatures", + "value": "5" + }, + { + "name": "NumberOfInstances", + "value": "150" + }, + { + "name": "NumberOfInstancesWithMissingValues", + "value": "0" + }, + { + "name": "NumberOfMissingValues", + "value": "0" + }, + { + "name": "NumberOfNumericFeatures", + "value": "4" + }, + { + "name": "NumberOfSymbolicFeatures", + "value": "0" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n360 - Please provide data set ID\\n361 - Unknown dataset. The data set with the given ID was not found in the database, or is not shared with you.\\n362 - No qualities found. The registered dataset did not contain any calculated qualities.\\n363 - Dataset not processed yet. The dataset was not processed yet, no qualities are available. Please wait for a few minutes.\\n364 - Dataset processed with error. The quality calculator has run into an error while processing the dataset. Please check whether it is a valid supported file. If so, contact the support team.\\n365 - Interval start or end illegal. There was a problem with the interval\\nstart or end.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/qualities": { + "post": { + "tags": [ + "data" + ], + "summary": "Upload dataset qualities", + "description": "Uploads dataset qualities. Upon success, it returns the data id.", + "operationId": "Api_data::data_qualities_upload", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.qualities) and an [XML example](https://www.openml.org/api/v1/xml_example/data.qualities).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "412": { + "description": "Precondition failed. An error code and message are returned.\\n381 - Something wrong with XML, please check did and evaluation_engine_id\\n382 - Please provide description xml\\n383 - Problem validating uploaded description file\\n384 - Dataset not processed yet\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/unprocessed/{data_engine_id}/{order}": { + "get": { + "tags": [ + "data" + ], + "summary": "Get a list of unprocessed datasets", + "description": "This call is for people running their own dataset processing engines. It returns the details of datasets that are not yet processed by the given processing engine. It doesn't process the datasets, it just returns the dataset info.", + "operationId": "Api_data::data_unprocessed", + "parameters": [ + { + "name": "data_engine_id", + "in": "path", + "description": "The ID of the data processing engine. You get this ID when you register a new data processing engine with OpenML. The ID of the main data processing engine is 1.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "order", + "in": "path", + "description": "When there are multiple datasets still to process, this defines which ones to return. Options are 'normal' - the oldest datasets, or 'random'.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of unprocessed datasets", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataUnprocessed" + }, + "example": { + "data_unprocessed": { + "run": [ + { + "did": "1", + "status": "deactivated", + "version": "2", + "name": "anneal", + "format": "ARFF" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n681 - No unprocessed datasets.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/data/qualities/unprocessed/{data_engine_id}/{order}": { + "post": { + "tags": [ + "data" + ], + "summary": "Get a list of datasets with unprocessed qualities", + "description": "This call is for people running their own dataset processing engines. It returns the details of datasets for which certain qualities are not yet processed by the given processing engine. It doesn't process the datasets, it just returns the dataset info.", + "operationId": "Api_data::dataqualities_unprocessed", + "parameters": [ + { + "name": "data_engine_id", + "in": "path", + "description": "The ID of the data processing engine. You get this ID when you register a new data processing engine with OpenML. The ID of the main data processing engine is 1.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "path", + "description": "When there are multiple datasets still to process, this defines which ones to return. Options are 'normal' - the oldest datasets, or 'random'.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "API key to authenticate the user", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "qualities", + "in": "query", + "description": "Comma-separated list of (at least two) quality names, e.g. 'NumberOfInstances,NumberOfFeatures'.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of unprocessed datasets", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DataUnprocessed" + }, + "example": { + "data_unprocessed": { + "run": [ + { + "did": "1", + "status": "deactivated", + "version": "2", + "name": "anneal", + "format": "ARFF" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n686 - Please specify the features the evaluation engine wants to calculate (at least 2).\\n687 - No unprocessed datasets according to the given set of meta-features.\\n688 - Illegal qualities.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/estimationprocedure/list": { + "get": { + "tags": [ + "estimationprocedure" + ], + "summary": "List all estimation procedures", + "description": "Returns an array with all model performance estimation procedures in the system.", + "operationId": "Api_estimationprocedure::estimationprocedure_list", + "responses": { + "200": { + "description": "A list of estimation procedures", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EstimationProcedureList" + }, + "example": { + "estimationprocedures": { + "estimationprocedure": [ + { + "id": "1", + "ttid": "1", + "name": "10-fold Crossvalidation", + "type": "crossvalidation", + "repeats": "1", + "folds": "10", + "stratified_sampling": "true" + }, + { + "id": "2", + "ttid": "1", + "name": "5 times 2-fold Crossvalidation", + "type": "crossvalidation", + "repeats": "5", + "folds": "2", + "stratified_sampling": "true" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n500 - No model performance estimation procedures available.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/evaluation/request/{evaluation_engine_id}/{order}": { + "get": { + "tags": [ + "evaluation" + ], + "summary": "Get an unevaluated run", + "description": "This call is for people running their own evaluation engines. It returns the details of a run that is not yet evaluated by the given evaluation engine. It doesn't evaluate the run, it just returns the run info.", + "operationId": "Api_evaluation::evaluation_request", + "parameters": [ + { + "name": "evaluation_engine_id", + "in": "path", + "description": "The ID of the evaluation engine. You get this ID when you register a new evaluation engine with OpenML. The ID of the main evaluation engine is 1.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "order", + "in": "path", + "description": "When there are multiple runs still to evaluate, this defines which one to return. Options are 'normal' - the oldest run, 'reverse' - the newest run, or 'random' - a random run.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of evaluations descriptions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvaluationRequest" + }, + "example": { + "evaluation_request": { + "run": [ + { + "setup_id": "68799271", + "upload_time": "2018-04-03 21:05:38", + "uploader": "1935", + "task_id": "3021", + "run_id": "8943712" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n100 - Function not valid.\\n545 - No unevaluated runs according to the criteria.\\n546 - Illegal filter.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/evaluation/list/{filters}": { + "get": { + "tags": [ + "evaluation" + ], + "summary": "List and filter evaluations", + "description": "List evaluations, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/evaluation/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all evaluations that match the constraints. A maximum of 10,000 results are returned, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain tasks, flows, setups, uploaders or runs.", + "operationId": "Api_evaluation::evaluation_list", + "parameters": [ + { + "name": "filters", + "in": "path", + "description": "Any combination of these filters\r\n /function/{name} - name of the evaluation measure, e.g. area_under_auc or predictive_accuracy. See the OpenML website for the complete list of measures.\r\n /tag/{tag} - returns only evaluations of runs tagged with the given tag.\r\n /run/{ids} - return only evaluations for specific runs, specified as a comma-separated list of run IDs, e.g. ''1,2,3''\r\n /task/{ids} - return only evaluations for specific tasks, specified as a comma-separated list of task IDs, e.g. ''1,2,3''\r\n /flow/{ids} - return only evaluations for specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3''\r\n /setup/{ids} - return only evaluations for specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3''\r\n /uploader/{ids} - return only evaluations uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n /per_fold/{true,false} - whether or not to return crossvalidation scores per fold. Defaults to 'false'. Setting it to 'true' leads to large numbers of results, use only for very specific sets of runs.\r\n /sort_order/{asc,desc} - sorts the results by the evaluation value, according to the selected evaluation measure (function)\r\n ", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of evaluations descriptions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvaluationList" + }, + "example": { + "evaluations": { + "evaluation": [ + { + "function": "area_under_roc_curve", + "upload_time": "2014-04-06 23:30:40", + "task_id": "68", + "run_id": "1", + "array_data": "[0,0.99113,0.898048,0.874862,0.791282,0.807343,0.820674]", + "value": "0.839359", + "uploader": "1", + "flow_id": "61" + }, + { + "function": "f_measure", + "upload_time": "2014-04-06 23:30:40", + "task_id": "68", + "run_id": "1", + "array_data": "[0,0,0.711934,0.735714,0.601363,0.435678,0.430913]", + "value": "0.600026", + "uploader": "1", + "flow_id": "61" + }, + { + "function": "predictive_accuracy", + "upload_time": "2014-04-06 23:30:40", + "task_id": "68", + "run_id": "1", + "array_data": [], + "value": "0.614634", + "uploader": "1", + "flow_id": "61" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n540 - Please provide at least task, flow or setup, uploader or run, to\\nfilter results, or limit the number of responses.\\n541 - The input parameters (task_id, setup_id, flow_id, run_id, uploader_id) did not meet the constraints (comma separated list of integers).\\n542 - There where no results. Check whether there are runs under the given constraint.\\n543 - Too many results. Given the constraints, there were still too many results. Please add filters to narrow down the list.\\n544 - Illegal filter specified.\\n545 - Offset specified without limit.\\n546 - Requested result limit too high.\\n547 - Per fold can only be set to value 'true' or 'false'.\\n548 - Per fold queries are experimental and require a fair amount of filters on resulting run records to keep the query fast (use, e.g., flow, setup, task and uploader filter)\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/evaluationmeasure/list": { + "get": { + "tags": [ + "evaluationmeasure" + ], + "summary": "List all evaluation measures", + "description": "Returns an array with all model evaluation measures in the system.", + "operationId": "Api_evaluationmeasure::evaluationmeasure_list", + "responses": { + "200": { + "description": "A list of evaluation measures", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/EvaluationMeasureList" + }, + "example": { + "evaluation_measures": { + "measures": { + "measure": [ + "area_under_roc_curve", + "average_cost", + "binominal_test", + "build_cpu_time" + ] + } + } + } + } + } + } + } + } + }, + "/flow/list/{filters}": { + "get": { + "tags": [ + "flow" + ], + "summary": "List and filter flows", + "description": "List flows, possibly filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/task/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all flows that match the constraints.", + "operationId": "Api_flow::flow_list", + "parameters": [ + { + "name": "filters", + "in": "path", + "description": "Any combination of these filters\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, tasks 11..15 will be returned. Both limit and offset need to be specified.\r\n /tag/{tag} - returns only tasks tagged with the given tag.\r\n /uploader/{id} - return only evaluations uploaded by a specific user, specified by user ID.\r\n ", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of flows", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FlowList" + }, + "example": { + "flows": { + "flow": [ + { + "id": "65", + "full_name": "weka.RandomForest(1)", + "name": "weka.RandomForest", + "version": "1", + "external_version": "Weka_3.7.10_9186", + "uploader": "1" + }, + { + "id": "66", + "full_name": "weka.IBk(1)", + "name": "weka.IBk", + "version": "1", + "external_version": "Weka_3.7.10_8034", + "uploader": "1" + }, + { + "id": "67", + "full_name": "weka.BayesNet_K2(1)", + "name": "weka.BayesNet_K2", + "version": "1", + "external_version": "Weka_3.7.10_8034", + "uploader": "1" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n500 - No results. There where no matches for the given constraints.\\n501 - Illegal filter specified.\\n502 - Filter values/ranges not properly specified.\\n503 - Can not specify an offset without a limit.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/flow/tag": { + "post": { + "tags": [ + "flow" + ], + "summary": "Tag a flow", + "description": "Tags a flow.", + "operationId": "Api_flow::flow_tag", + "parameters": [ + { + "name": "flow_id", + "in": "query", + "description": "Id of the flow.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the tagged flow", + "content": { + "application/json": { + "schema": { + "properties": { + "flow_tag": { + "$ref": "#/components/schemas/inline_response_200_12_flow_tag" + } + }, + "type": "object" + }, + "example": { + "flow_tag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\\n474 - Internal error tagging the entity. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/flow/untag": { + "post": { + "tags": [ + "flow" + ], + "summary": "Untag a flow", + "description": "Untags a flow.", + "operationId": "Api_flow::flow_untag", + "parameters": [ + { + "name": "flow_id", + "in": "query", + "description": "Id of the flow.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the untagged flow", + "content": { + "application/json": { + "schema": { + "properties": { + "flow_untag": { + "$ref": "#/components/schemas/inline_response_200_13_flow_untag" + } + }, + "type": "object" + }, + "example": { + "flow_untag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged\\nby another user. Hence you cannot delete it.\\n479 - Internal error removing the tag. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/flow/exists/{name}/{version}": { + "get": { + "tags": [ + "flow" + ], + "summary": "Check whether flow exists", + "description": "Checks whether a flow with the given name and (external) version exists.", + "operationId": "Api_flow::flow_exists", + "parameters": [ + { + "name": "name", + "in": "path", + "description": "The name of the flow.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "version", + "in": "path", + "description": "The external version of the flow", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of flows", + "content": { + "application/json": { + "schema": { + "properties": { + "flow_exists": { + "$ref": "#/components/schemas/inline_response_200_10_flow_exists" + } + }, + "type": "object" + }, + "example": { + "flow_exists": { + "exists": "true", + "id": "65" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n330 - Mandatory fields not present. Please provide name and external_version.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/flow/{id}": { + "get": { + "tags": [ + "flow" + ], + "summary": "Get flow description", + "description": "Returns information about a flow. The information includes the name, information about the creator, dependencies, parameters, run instructions and more.", + "operationId": "Api_flow::flow", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the flow.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "A flow description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Flow" + }, + "example": { + "flow": { + "id": "100", + "uploader": "1", + "name": "weka.J48", + "version": "2", + "external_version": "Weka_3.7.5_9117", + "description": "...", + "upload_date": "2014-04-23 18:00:36", + "language": "Java", + "dependencies": "Weka_3.7.5", + "parameter": [ + { + "name": "A", + "data_type": "flag", + "default_value": [], + "description": "Laplace smoothing..." + }, + { + "name": "C", + "data_type": "option", + "default_value": "0.25", + "description": "Set confidence threshold..." + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n180 - Please provide flow id.\\n181 - Unknown flow. The flow with the given ID was not found in the database.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "tags": [ + "flow" + ], + "summary": "Delete a flow", + "description": "Deletes a flow. Upon success, it returns the ID of the deleted flow.", + "operationId": "Api_flow::flow_delete", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the flow.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "api_key", + "in": "query", + "description": "API key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ID of the deleted flow", + "content": { + "application/json": { + "schema": { + "properties": { + "flow_delete": { + "$ref": "#/components/schemas/inline_response_200_8_flow_delete" + } + }, + "type": "object" + }, + "example": { + "flow_delete": { + "id": "4328" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n320 - Please provide API key. In order to remove your content, please authenticate.\\n321 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\\n322 - Flow does not exists. The flow ID could not be linked to an existing flow.\\n323 - Flow is not owned by you. The flow is owned by another user. Hence you cannot delete it.\\n324 - Flow is in use by other content. Can not be deleted. The flow is used in runs, evaluations or as a component of another flow. Delete other content before deleting this flow.\\n325 - Deleting flow failed. Deleting the flow failed. Please contact\\nsupport team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/flow": { + "post": { + "tags": [ + "flow" + ], + "summary": "Upload a flow", + "description": "Uploads a flow. Upon success, it returns the flow id.", + "operationId": "Api_flow::flow_upload", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the flow. Only name and description are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.implementation.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/flow).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "flow", + "in": "query", + "description": "The actual flow, being a source (or binary) file.", + "required": false, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the uploaded flow", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_flow": { + "$ref": "#/components/schemas/inline_response_200_9_upload_flow" + } + }, + "type": "object" + }, + "example": { + "upload_flow": { + "id": "2520" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n160 - Error in file uploading. There was a problem with the file upload.\\n161 - Please provide description xml.\\n163 - Problem validating uploaded description file. The XML description format does not meet the standards.\\n164 - Flow already stored in database. Please change name or version number\\n165 - Failed to insert flow. There can be many causes for this error. If you included the implements field, it should be an existing entry in the algorithm or math_function table. Otherwise it could be an internal server error. Please contact API support team.\\n166 - Failed to add flow to database. Internal server error, please contact API administrators\\n167 - Illegal files uploaded. An non required file was uploaded.\\n168 - The provided md5 hash equals not the server generated md5 hash of the file.\\n169 - Please provide API key. In order to share content, please authenticate and provide API key.\\n170 - Authentication failed. The API key was not valid. Please try to login again, or contact API administrators\\n171 - Flow already exists. This flow is already in the database\\n172 - XSD not found. Please contact API support team\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run/tag": { + "post": { + "tags": [ + "run" + ], + "summary": "Tag a run", + "description": "Tags a run.", + "operationId": "Api_run::run_tag", + "parameters": [ + { + "name": "run_id", + "in": "query", + "description": "Id of the run.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the tagged run", + "content": { + "application/json": { + "schema": { + "properties": { + "run_tag": { + "$ref": "#/components/schemas/inline_response_200_19_run_tag" + } + }, + "type": "object" + }, + "example": { + "run_tag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\\n474 - Internal error tagging the entity. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run/untag": { + "post": { + "tags": [ + "run" + ], + "summary": "Untag a run", + "description": "Untags a run.", + "operationId": "Api_run::run_untag", + "parameters": [ + { + "name": "run_id", + "in": "query", + "description": "Id of the run.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the untagged run", + "content": { + "application/json": { + "schema": { + "properties": { + "run_untag": { + "$ref": "#/components/schemas/inline_response_200_20_run_untag" + } + }, + "type": "object" + }, + "example": { + "run_untag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\\n479 - Internal error removing the tag. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run/list/{filters}": { + "get": { + "tags": [ + "run" + ], + "summary": "List and filter runs", + "description": "List runs, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/run/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all runs that match the constraints. A maximum of 10,000 results are returned, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain tasks, flows, setups, or uploaders.", + "operationId": "Api_run::run_list", + "parameters": [ + { + "name": "filters", + "in": "path", + "description": "Any combination of these filters\r\n /tag/{tag} - return only runs tagged with the given tag.\r\n /run/{ids} - return only specific runs, specified as a comma-separated list of run IDs, e.g. ''1,2,3''\r\n /task/{ids} - return only runs on specific tasks, specified as a comma-separated list of task IDs, e.g. ''1,2,3''\r\n /flow/{ids} - return only runs on specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3''\r\n /setup/{ids} - return only runs with specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3''\r\n /uploader/{ids} - return only runs uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n ", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of runs descriptions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RunList" + }, + "example": { + "runs": { + "run": [ + { + "upload_time": "2014-04-06 23:30:40", + "task_id": "28", + "run_id": "100", + "error_message": [], + "setup_id": "12", + "uploader": "1", + "flow_id": "67" + }, + { + "upload_time": "2014-04-06 23:30:40", + "task_id": "48", + "run_id": "101", + "error_message": [], + "setup_id": "6", + "uploader": "1", + "flow_id": "61" + }, + { + "upload_time": "2014-04-06 23:30:40", + "task_id": "41", + "run_id": "102", + "error_message": [], + "setup_id": "3", + "uploader": "1", + "flow_id": "58" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n510 - Please provide at least task, flow or setup, uploader or run, to filter results, or limit the number of responses. The number of runs is huge. Please limit the result space.\\n511 - Input not safe. The input parameters (task_id, setup_id, flow_id, run_id, uploader_id) did not meet the constraints (comma separated list of integers).\\n512 - There where no results. Check whether there are runs under the given constraint.\\n513 - Too many results. Given the constraints, there were still too many results. Please add filters to narrow down the list.\\n514 - Illegal filter specified.\\n515 - Offset specified without limit.\\n516 - Requested result limit too high.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run/{id}": { + "get": { + "tags": [ + "run" + ], + "summary": "Get run description", + "description": "Returns information about a run. The information includes the name, information about the creator, dependencies, parameters, run instructions and more.", + "operationId": "Api_run::run", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the run.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "A run description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Run" + }, + "example": { + "run": { + "run_id": "100", + "uploader": "1", + "uploader_name": "Jan van Rijn", + "task_id": "28", + "task_type": "Supervised Classification", + "task_evaluation_measure": "predictive_accuracy", + "flow_id": "67", + "flow_name": "weka.BayesNet_K2(1)", + "setup_string": "weka.classifiers.bayes.BayesNet -- -D -Q weka.classifiers.bayes.net.search.local.K2 -- -P 1 -S BAYES -E weka.classifiers.bayes.net.estimate.SimpleEstimator -- -A 0.5", + "parameter_setting": [ + { + "name": "D", + "value": "true" + }, + { + "name": "Q", + "value": "weka.classifiers.bayes.net.search.local.K2" + }, + { + "name": "P", + "value": "1" + }, + { + "name": "S", + "value": "BAYES" + } + ], + "input_data": { + "dataset": { + "did": "28", + "name": "optdigits", + "url": "https:\\\\/\\\\/www.openml.org\\\\/data\\\\/download\\\\/28\\\\/dataset_28_optdigits.arff" + } + }, + "output_data": { + "file": [ + { + "did": "48838", + "file_id": "261", + "name": "description", + "url": "https:\\\\/\\\\/www.openml.org\\\\/data\\\\/download\\\\/261\\\\/weka_generated_run935374685998857626.xml" + }, + { + "did": "48839", + "file_id": "262", + "name": "predictions", + "url": "https:\\\\/\\\\/www.openml.org\\\\/data\\\\/download\\\\/262\\\\/weka_generated_predictions576954524972002741.arff" + } + ], + "evaluation": [ + { + "name": "area_under_roc_curve", + "flow_id": "4", + "value": "0.990288", + "array_data": "[0.99724,0.989212,0.992776,0.994279,0.980578,0.98649,0.99422,0.99727,0.994858,0.976143]" + }, + { + "name": "confusion_matrix", + "flow_id": "10", + "array_data": "[[544,1,0,0,7,0,1,0,0,1],[0,511,21,1,0,1,3,1,5,28],[0,7,511,1,0,1,0,3,23,11],[0,2,2,519,0,3,0,12,16,18],[0,3,0,0,528,0,4,21,6,6],[0,1,0,7,5,488,2,0,4,51],[1,7,0,0,2,0,548,0,0,0],[0,2,0,1,9,1,0,545,4,4],[1,25,2,2,3,6,2,1,503,9],[0,7,0,20,16,5,0,19,9,486]]" + }, + { + "name": "f_measure", + "flow_id": "12", + "value": "0.922723", + "array_data": "[0.989091,0.898857,0.935041,0.92431,0.927944,0.918156,0.980322,0.933219,0.895018,0.826531]" + }, + { + "name": "kappa", + "flow_id": "13", + "value": "0.913601" + } + ] + } + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n220 - Please provide run ID. In order to view run details, please provide the run ID.\\n221 - Run not found. The run ID was invalid, run does not exist (anymore).\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "tags": [ + "run" + ], + "summary": "Delete run", + "description": "Deletes a run. Upon success, it returns the ID of the deleted run.", + "operationId": "Api_run::run_delete", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the run.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "api_key", + "in": "query", + "description": "API key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ID of the deleted run", + "content": { + "application/json": { + "schema": { + "properties": { + "data_delete": { + "$ref": "#/components/schemas/inline_response_200_17_data_delete" + } + }, + "type": "object" + }, + "example": { + "run_delete": { + "id": "2520" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n390 - Please provide API key. In order to remove your content, please authenticate.\\n391 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators\\n392 - Run does not exists. The run ID could not be linked to an existing run.\\n393 - Run is not owned by you. The run was owned by another user. Hence you cannot delete it.\\n394 - Deleting run failed. Deleting the run failed. Please contact support team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run/reset/{id}": { + "get": { + "tags": [ + "run" + ], + "summary": "Resets a run.", + "description": "Removes all run evaluations. When a run is reset, the runs will automatically be evaluated as soon as they are picked up by the evaluation engine again.", + "operationId": "Api_run::run_reset", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Run ID.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the evaluated run", + "content": { + "application/json": { + "schema": { + "properties": { + "run_reset": { + "$ref": "#/components/schemas/inline_response_200_21_upload_flow" + } + }, + "type": "object" + }, + "example": { + "run_reset": { + "id": "2520" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n412 - Run does not exist\\n413 - Run is not owned by you\\n394 - Resetting run failed\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run": { + "post": { + "tags": [ + "run" + ], + "summary": "Upload run", + "description": "Uploads a run. Upon success, it returns the run id.", + "operationId": "Api_run::run_upload", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/run).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "predictions", + "in": "query", + "description": "The predictions generated by the run", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "model_readable", + "in": "query", + "description": "The human-readable model generated by the run", + "required": false, + "schema": { + "type": "file" + } + }, + { + "name": "model_serialized", + "in": "query", + "description": "The serialized model generated by the run", + "required": false, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the uploaded run", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_flow": { + "$ref": "#/components/schemas/inline_response_200_18_upload_flow" + } + }, + "type": "object" + }, + "example": { + "upload_run": { + "id": "2520" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n201 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\\n202 - Please provide run XML.\\n203 - Could not validate run xml by XSD. Please double check that the xml is valid.\\n204 - Unknown task. The task with the given ID was not found in the database.\\n205 - Unknown flow. The flow with the given ID was not found in the database.\\n206 - Invalid number of files. The number of uploaded files did not match the number of files expected for the task type\\n207 - File upload failed. One of the files uploaded has a problem.\\n208 - Error inserting setup record. Please contact api administrators\\n210 - Unable to store run. Please contact api administrators.\\n211 - Dataset not in database. One of the datasets of the task was not included in database, please contact api administrators.\\n212 - Unable to store file. Please contact api administrators.\\n213 - Parameter in run xml unknown. One of the parameters provided in the run xml is not registered as parameter for the flow nor its components.\\n214 - Unable to store input setting. Please contact API support team.\\n215 - Unable to evaluate predictions. Please contact API support team.\\n216 - Error thrown by Java Application. Additional information field is provided.\\n217 - Error processing output data. Unknown or inconsistent evaluation measure. One of the provided evaluation measures could not be matched with a record in the math_function or flow table.\\n218 - Wrong flow associated with run. The flow implements a math_function, which is unable to generate predictions. Please select another flow.\\n219 - Error reading the XML document. The XML description file could not be verified.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run/trace/{id}": { + "get": { + "tags": [ + "run" + ], + "summary": "Get run trace", + "description": "Returns the optimization trace of run. The trace contains every setup tried, its evaluation, and whether it was selected.", + "operationId": "Api_run::run_trace", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the run.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "A run trace description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RunTrace" + }, + "example": { + "trace": { + "run_id": "573055", + "trace_iteration": { + "repeat": "0", + "fold": "0", + "iteration": "1", + "setup_string": { + "parameter_minNumObj": "1", + "parameter_confidenceFactor": "0.25" + }, + "evaluation": "94.074074", + "selected": "true" + } + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n570 - No successful trace associated with this run\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "post": { + "tags": [ + "run" + ], + "summary": "Upload run trace", + "description": "Uploads a run trace. Upon success, it returns the run id.", + "operationId": "Api_run::run_trace_upload", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the run.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "description", + "in": "query", + "description": "An XML file describing the trace. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.trace) and an [XML example](https://www.openml.org/api/v1/xml_example/run.trace).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the run with the trace", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_flow": { + "$ref": "#/components/schemas/inline_response_200_23_upload_flow" + } + }, + "type": "object" + }, + "example": { + "run_trace": { + "id": "2520" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n561 - Problem with uploaded trace file.\\n562 - Problem validating xml trace file.\\n563 - Problem loading xml trace file.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/run/evaluate": { + "post": { + "tags": [ + "run" + ], + "summary": "Uploads a run evaluation", + "description": "Uploads a run evaluation. When successful, it returns the run id.", + "operationId": "Api_run::run_evaluate", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the run evaluation.Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.evaluate) and an [XML example](https://www.openml.org/api/v1/xml_example/run.evaluate).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the evaluated run", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_flow": { + "$ref": "#/components/schemas/inline_response_200_21_upload_flow" + } + }, + "type": "object" + }, + "example": { + "run_evaluate": { + "id": "2520" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n422 - Upload problem description XML\\n423 - Problem validating uploaded description file\\n424 - Problem opening description xml\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/setup/tag": { + "post": { + "tags": [ + "setup" + ], + "summary": "Tag a setup", + "description": "Tags a setup.", + "operationId": "Api_setup::setup_tag", + "parameters": [ + { + "name": "setup_id", + "in": "query", + "description": "Id of the setup.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the tagged setup", + "content": { + "application/json": { + "schema": { + "properties": { + "flow_tag": { + "$ref": "#/components/schemas/inline_response_200_15_flow_tag" + } + }, + "type": "object" + }, + "example": { + "setup_tag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\\n474 - Internal error tagging the entity. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/setup/untag": { + "post": { + "tags": [ + "setup" + ], + "summary": "Untag a setup", + "description": "Untags a setup.", + "operationId": "Api_setup::setup_untag", + "parameters": [ + { + "name": "setup_id", + "in": "query", + "description": "Id of the setup.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the untagged setup", + "content": { + "application/json": { + "schema": { + "properties": { + "flow_untag": { + "$ref": "#/components/schemas/inline_response_200_16_flow_untag" + } + }, + "type": "object" + }, + "example": { + "setup_untag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged\\nby another user. Hence you cannot delete it.\\n479 - Internal error removing the tag. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/setup/{id}": { + "get": { + "tags": [ + "setup" + ], + "summary": "Get a hyperparameter setup", + "description": "Returns information about a setup. The information includes the list of hyperparameters, with name, value, and default value.", + "operationId": "Api_setup::setup", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the hyperparameter setup (configuration). These IDs are stated in run descriptions.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "A setup description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Setup" + }, + "example": { + "setup_parameters": { + "flow_id": "59", + "parameter": [ + { + "full_name": "weka.JRip(1)_F", + "parameter_name": "F", + "data_type": "option", + "default_value": "3", + "value": "3" + }, + { + "full_name": "weka.JRip(1)_N", + "parameter_name": "N", + "data_type": "option", + "default_value": "2.0", + "value": "2.0" + }, + { + "full_name": "weka.JRip(1)_O", + "parameter_name": "O", + "data_type": "option", + "default_value": "2", + "value": "2" + }, + { + "full_name": "weka.JRip(1)_S", + "parameter_name": "S", + "data_type": "option", + "default_value": "1", + "value": "1" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n280 - Please provide setup ID. In order to view setup details, please provide the run ID\\n281 - Setup not found. The setup ID was invalid, or setup does not exist (anymore).\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "tags": [ + "setup" + ], + "summary": "Delete setup", + "description": "Deletes a setup. Upon success, it returns the ID of the deleted setup.", + "operationId": "Api_setup::setup_delete", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the setup.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ID of the deleted setup", + "content": { + "application/json": { + "schema": { + "properties": { + "study_delete": { + "$ref": "#/components/schemas/inline_response_200_14_study_delete" + } + }, + "type": "object" + }, + "example": { + "setup_delete": { + "id": "1" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n401 - Authentication failed. Please provide API key. In order to remove your content, please authenticate.\\n402 - Setup does not exists. The setup ID could not be linked to an existing setup.\\n404 - Setup deletion failed. Setup is in use by other content (runs, schedules, etc). Can not be deleted.\\n405 - Setup deletion failed. Please try again later.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/setup/list/{filters}": { + "get": { + "tags": [ + "setup" + ], + "summary": "List and filter setups", + "description": "List setups, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/setup/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all evaluations that match the constraints. A maximum of 1,000 results are returned at a time, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain flows, setups, or tags.", + "operationId": "Api_setup::setup_list", + "parameters": [ + { + "name": "filters", + "in": "path", + "description": "Any combination of these filters\r\n /tag/{tag} - returns only setups tagged with the given tag.\r\n /flow/{ids} - return only setups for specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3''\r\n /setup/{ids} - return only specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n ", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of setup descriptions", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupList" + }, + "example": { + "setups": { + "setup": [ + { + "setup_id": "10", + "flow_id": "65", + "parameter": [ + { + "id": "4144", + "flow_id": "65", + "flow_name": "weka.RandomForest", + "full_name": "weka.RandomForest(1)_I", + "parameter_name": "I", + "data_type": "option", + "default_value": "10", + "value": "10" + }, + { + "id": "4145", + "flow_id": "65", + "flow_name": "weka.RandomForest", + "full_name": "weka.RandomForest(1)_K", + "parameter_name": "K", + "data_type": "option", + "default_value": "0", + "value": "0" + } + ] + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n670 - Please specify at least one filter.\\n671 - Illegal filter.\\n672 - Illegal filter input.\\n673 - Result set too big. Please use one of the filters or the limit option.\\n674 - No results, please check the filter.\\n675 - Cannot specify offset without limit.\\n676 - Requested result limit too high.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/study": { + "post": { + "tags": [ + "study" + ], + "summary": "Create new study", + "description": "Creates a new study. Upon success, it returns the study id.", + "operationId": "Api_study::study_create", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the study. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.study.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/study).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the uploaded study", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_study": { + "$ref": "#/components/schemas/inline_response_200_25_upload_study" + } + }, + "type": "object" + }, + "example": { + "upload_study": { + "id": "4328" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n1031 - Description file not present. Please upload the study description.\\n1032 - Problem validating uploaded description file. The XML description format does not meet the standards. See the XSD schema.\\n1033 - Illegal main entity type. Currently only collections of tasks and can be created.\\n1034 - Linked entities are not of the correct type fot this study.\\n1035 - Benchmark suites can only be linked to run studies.\\n1036 - Referred benchmark suite cannot be found.\\n1037 - Referred benchmark suite should be a task collection.\\n1038 - Study alias is not unique.\\n1039 - Dataset insertion problem. Please contact the administrators.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/study/{id}/attach": { + "post": { + "tags": [ + "study" + ], + "summary": "Attach a new entity to a study", + "description": "Attach a new entity to an exising study. Upon success, it returns the study id, type, and linked entities.", + "operationId": "Api_study::study_attach", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the study. Supplied in the URL path.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "ids", + "in": "query", + "description": "Comma-separated list of entity IDs to be attached to the study. For instance, if this is a run study, the list of run IDs that need to be added (attached) to the study. Must be supplied as a POST variable.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Properties of the updated study", + "content": { + "application/json": { + "schema": { + "properties": { + "study_attach": { + "$ref": "#/components/schemas/inline_response_200_26_study_attach" + } + }, + "type": "object" + }, + "example": { + "study_attach": { + "id": "1", + "main_entity_type": "task", + "linked_entities": "5" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n1041 - Could not find study. Check the study ID in your request.\\n1042 - Cannnot attach entities to legacy studies.\\n1043 - Please provide POST field 'ids'.\\n1044 - Please ensure that the 'ids' in the POST field is a list of natural numbers.\\n1045 - Could not attach entities to the study. It appears as if the entity does not exist.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/study/{id}/detach": { + "post": { + "tags": [ + "study" + ], + "summary": "Detach an entity from a study", + "description": "Detach an entity from an exising study. Upon success, it returns the study id, type, and linked entities.", + "operationId": "Api_study::study_detach", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the study.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "ids", + "in": "query", + "description": "Comma-separated list of entity IDs to be detached from the study. For instance, if this is a run study, the list of run IDs that need to be removed (detached) from the study. Must be supplied as a POST variable.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Properties of the updated study", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_study": { + "$ref": "#/components/schemas/inline_response_200_26_study_attach" + } + }, + "type": "object" + }, + "example": { + "study_detach": { + "id": "1", + "main_entity_type": "task", + "linked_entities": "5" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n1041 - Could not find study. Check the study ID in your request.\\n1042 - Cannot attach entities to legacy studies.\\n1043 - Please provide POST field 'ids'.\\n1044 - Please ensure that the 'ids' in the POST field is a list of natural numbers.\\n1046 - Could not detach entities from the study. It appears as if the entity does not exist. \\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/study/{id}": { + "get": { + "tags": [ + "study" + ], + "summary": "Get study description by study id or alias", + "description": "Returns information about the study with the given id or alias.", + "operationId": "Api_study::study_get", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID or alias of the study.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A study description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Study" + }, + "example": { + "study": { + "id": "99", + "main_entity_type": "task", + "name": "CC18 benchmark suite", + "description": "CC18 benchmark suite", + "creation_date": "2019-02-16T17:35:58", + "creator": "1159", + "data": { + "data_id": [ + "1", + "2", + "3" + ] + }, + "tasks": { + "task_id": [ + "1", + "2", + "3" + ] + } + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n601 - Unknown study. The study with the given id or alias was not found in the database\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "tags": [ + "study" + ], + "summary": "Delete study", + "description": "Deletes a study. Upon success, it returns the ID of the deleted study.", + "operationId": "Api_study::study_delete", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the study.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ID of the deleted study", + "content": { + "application/json": { + "schema": { + "properties": { + "study_delete": { + "$ref": "#/components/schemas/inline_response_200_24_study_delete" + } + }, + "type": "object" + }, + "example": { + "study_delete": { + "id": "1" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n591 - Please provide API key. In order to remove your content, please authenticate.\\n592 - Study does not exists. The study ID could not be linked to an existing study.\\n593 - Study deletion failed. Please try again later.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/study/list/{filters}": { + "get": { + "tags": [ + "study" + ], + "summary": "List all studies (collections of items)", + "description": "List studies, optionally filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/study/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all studies that match the constraints.", + "operationId": "Api_study::study_list", + "parameters": [ + { + "name": "filters", + "in": "path", + "description": "Any combination of these filters\r\n /main_entity_type/{type} - only return studies collecting entities of a given type (e.g. 'task' or 'run').\r\n /uploader/{ids} - return only evaluations uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n ", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of studies", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/StudyList" + }, + "example": { + "study_list": { + "study": [ + { + "id": "1", + "alias": "Study_1", + "name": "A large-scale comparison of classification algorithms", + "creation_date": "2017-07-20 15:51:20", + "creator": "2" + }, + { + "id": "2", + "alias": "Study_2", + "name": "Fast Algorithm Selection using Learning Curves", + "creation_date": "2017-07-20 15:51:20", + "creator": "2" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/task/tag": { + "post": { + "tags": [ + "task" + ], + "summary": "Tag a task", + "description": "Tags a task.", + "operationId": "Api_task::task_tag", + "parameters": [ + { + "name": "task_id", + "in": "query", + "description": "Id of the task.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The id of the tagged task", + "content": { + "application/json": { + "schema": { + "properties": { + "task_tag": { + "$ref": "#/components/schemas/inline_response_200_6_task_tag" + } + }, + "type": "object" + }, + "example": { + "task_tag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n470 - In order to add a tag, please upload the entity id (either data_id, task_id, flow_id, run_id) and tag (the name of the tag).\\n471 - Entity not found. The provided entity_id {data_id, task_id, flow_id, run_id} does not correspond to an existing entity.\\n472 - Entity already tagged by this tag. The entity {dataset, task, flow, run} already had this tag.\\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\\n474 - Internal error tagging the entity. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/task/untag": { + "post": { + "tags": [ + "task" + ], + "summary": "Untag a task", + "description": "Untags a task.", + "operationId": "Api_task::task_untag", + "parameters": [ + { + "name": "task_id", + "in": "query", + "description": "Id of the task.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "tag", + "in": "query", + "description": "Tag name", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A the features of the task", + "content": { + "application/json": { + "schema": { + "properties": { + "task_untag": { + "$ref": "#/components/schemas/inline_response_200_7_task_untag" + } + }, + "type": "object" + }, + "example": { + "task_untag": { + "id": "2" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, task_id, flow_id, run_id) and tag (the name of the tag).\\n476 - Entity {dataset, task, flow, run} not found. The provided entity_id {data_id, task_id, flow_id, run_id} does not correspond to an existing entity.\\n477 - Tag not found. The provided tag is not associated with the entity {dataset, task, flow, run}.\\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\\n479 - Internal error removing the tag. Please contact OpenML Team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/task/list/{filters}": { + "get": { + "tags": [ + "task" + ], + "summary": "List and filter tasks", + "description": "List tasks, possibly filtered by a range of properties from the task itself or from the underlying dataset. Any number of properties can be combined by listing them one after the other in the form '/task/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all tasks that match the constraints.", + "operationId": "Api_task::task_list", + "parameters": [ + { + "name": "filters", + "in": "path", + "description": "Any combination of these filters\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, tasks 11..15 will be returned. Both limit and offset need to be specified.\r\n /status/{status} - returns only tasks with a given status, either 'active', 'deactivated', or 'in_preparation'.\r\n /type/{type_id} - returns only tasks with a given task type id. See the list of task types of the ID's (e.g. 1 = Supervised Classification).\r\n /tag/{tag} - returns only tasks tagged with the given tag.\r\n /data_tag/{tag} - returns only tasks for which the underlying dataset is tagged with the given tag.\r\n /{data_quality}/{range} - returns only tasks for which the underlying datasets have certain qualities. {data_quality} can be data_id, data_name, number_instances, number_features, number_classes, number_missing_values. {range} can be a specific value or a range in the form 'low..high'. Multiple qualities can be combined, as in 'number_instances/0..50/number_features/0..10'.\r\n ", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "A list of tasks with the given tag", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TaskList" + }, + "example": { + "task": { + "task": [ + { + "task_id": "1", + "task_type": "Supervised Classification", + "did": "1", + "name": "anneal", + "status": "active", + "format": "ARFF", + "input": [ + { + "name": "estimation_procedure", + "value": "1" + }, + { + "name": "evaluation_measures", + "value": "predictive_accuracy" + }, + { + "name": "source_data", + "value": "1" + }, + { + "name": "target_feature", + "value": "class" + } + ], + "quality": [ + { + "name": "MajorityClassSize", + "value": "684" + }, + { + "name": "MaxNominalAttDistinctValues", + "value": "10.0" + }, + { + "name": "MinorityClassSize", + "value": "0" + }, + { + "name": "NumBinaryAtts", + "value": "14.0" + }, + { + "name": "NumberOfClasses", + "value": "6" + }, + { + "name": "NumberOfFeatures", + "value": "39" + }, + { + "name": "NumberOfInstances", + "value": "898" + }, + { + "name": "NumberOfInstancesWithMissingValues", + "value": "0" + }, + { + "name": "NumberOfMissingValues", + "value": "0" + }, + { + "name": "NumberOfNumericFeatures", + "value": "6" + }, + { + "name": "NumberOfSymbolicFeatures", + "value": "32" + } + ], + "tag": [ + "basic", + "study_1", + "study_7", + "under100k", + "under1m" + ] + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n480 - Illegal filter specified.\\n481 - Filter values/ranges not properly specified.\\n482 - No results. There where no matches for the given constraints.\\n483 - Can not specify an offset without a limit.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/task/{id}": { + "get": { + "tags": [ + "task" + ], + "summary": "Get task description", + "description": "Returns information about a task. The information includes the task type, input data, train/test sets, and more.", + "operationId": "Api_task::task", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the task.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "A task description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Task" + }, + "example": { + "task": { + "task_id": "1", + "task_type": "Supervised Classification", + "input": [ + { + "name": "source_data", + "data_set": { + "data_set_id": "1", + "target_feature": "class" + } + }, + { + "name": "estimation_procedure", + "estimation_procedure": { + "type": "crossvalidation", + "data_splits_url": "https://www.openml.org/api_splits/get/1/Task_1_splits.arff", + "parameter": [ + { + "name": "number_repeats", + "value": "1" + }, + { + "name": "number_folds", + "value": "10" + }, + { + "name": "percentage" + }, + { + "name": "stratified_sampling", + "value": "true" + } + ] + } + }, + { + "name": "cost_matrix", + "cost_matrix": [] + }, + { + "name": "evaluation_measures", + "evaluation_measures": { + "evaluation_measure": "predictive_accuracy" + } + } + ], + "output": { + "name": "predictions", + "predictions": { + "format": "ARFF", + "feature": [ + { + "name": "repeat", + "type": "integer" + }, + { + "name": "fold", + "type": "integer" + }, + { + "name": "row_id", + "type": "integer" + }, + { + "name": "confidence.classname", + "type": "numeric" + }, + { + "name": "prediction", + "type": "string" + } + ] + } + }, + "tag": [ + "basic", + "study_1", + "under100k", + "under1m" + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n150 - Please provide task_id.\\n151 - Unknown task. The task with the given id was not found in the database\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + }, + "delete": { + "tags": [ + "task" + ], + "summary": "Delete task", + "description": "Deletes a task. Upon success, it returns the ID of the deleted task.", + "operationId": "Api_task::task_delete", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "Id of the task.", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "ID of the deleted task", + "content": { + "application/json": { + "schema": { + "properties": { + "task_delete": { + "$ref": "#/components/schemas/inline_response_200_4_task_delete" + } + }, + "type": "object" + }, + "example": { + "task_delete": { + "id": "4328" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n450 - Please provide API key. In order to remove your content, please authenticate.\\n451 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\\n452 - Task does not exists. The task ID could not be linked to an existing task.\\n454 - Task is executed in some runs. Delete these first.\\n455 - Deleting the task failed. Please contact support team.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/task": { + "post": { + "tags": [ + "task" + ], + "summary": "Upload task", + "description": "Uploads a task. Upon success, it returns the task id.", + "operationId": "Api_task::task_upload", + "parameters": [ + { + "name": "description", + "in": "query", + "description": "An XML file describing the task. Only name, description, and task format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.task.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/task).", + "required": true, + "schema": { + "type": "file" + } + }, + { + "name": "api_key", + "in": "query", + "description": "Api key to authenticate the user", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Id of the uploaded task", + "content": { + "application/json": { + "schema": { + "properties": { + "upload_task": { + "$ref": "#/components/schemas/inline_response_200_5_upload_task" + } + }, + "type": "object" + }, + "example": { + "upload_task": { + "id": "4328" + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n530 - Description file not present. Please upload the task description.\\n531 - Internal error. Please contact api support team\\n532 - Problem validating uploaded description file. The XML description format does not meet the standards\\n533 - Task already exists.\\n534 - Error creating the task.\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/tasktype/list": { + "get": { + "tags": [ + "tasktype" + ], + "summary": "List all task types", + "description": "Returns an array with all task types in the system.", + "responses": { + "default": { + "description": "Unexpected error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + }, + "200": { + "description": "A task description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TaskTypeList" + }, + "example": { + "task_types": { + "task_type": [ + { + "id": "1", + "name": "Supervised Classification", + "description": "In supervised classification, you are given ...", + "creator": "Joaquin Vanschoren, Jan van Rijn, Luis Torgo, Bernd Bischl" + }, + { + "id": "2", + "name": "Supervised Regression", + "description": "Given a dataset with a numeric target ...", + "creator": "Joaquin Vanschoren, Jan van Rijn, Luis Torgo, Bernd Bischl" + } + ] + } + } + } + } + } + } + } + }, + "/tasktype/{id}": { + "get": { + "tags": [ + "tasktype" + ], + "summary": "Get task type description", + "description": "Returns information about a task type. The information includes a description, the given inputs and the expected outputs.", + "parameters": [ + { + "name": "id", + "in": "path", + "description": "ID of the task.", + "required": true, + "schema": { + "type": "integer" + } + } + ], + "responses": { + "200": { + "description": "A task type description", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/TaskType" + }, + "example": { + "task_type": { + "id": "1", + "name": "Supervised Classification", + "description": "In supervised classification, you are given an input dataset in which instances are labeled with a certain class. The goal is to build a model that predicts the class for future unlabeled instances. The model is evaluated using a train-test procedure, e.g. cross-validation.

\\\r\n * \\\r\n * To make results by different users comparable, you are given the exact train-test folds to be used, and you need to return at least the predictions generated by your model for each of the test instances. OpenML will use these predictions to calculate a range of evaluation measures on the server.

\\\r\n * \\\r\n * You can also upload your own evaluation measures, provided that the code for doing so is available from the implementation used. For extremely large datasets, it may be infeasible to upload all predictions. In those cases, you need to compute and provide the evaluations yourself.

\\\r\n * \\\r\n * Optionally, you can upload the model trained on all the input data. There is no restriction on the file format, but please use a well-known format or PMML.", + "creator": [ + "Joaquin Vanschoren", + "Jan van Rijn", + "Luis Torgo", + "Bernd Bischl" + ], + "contributor": [ + "Bo Gao", + "Simon Fischer", + "Venkatesh Umaashankar", + "Michael Berthold", + "Bernd Wiswedel", + "Patrick Winter" + ], + "creation_date": "2013-01-24 00:00:00", + "input": [ + { + "name": "source_data", + "requirement": "required", + "data_type": "numeric" + }, + { + "name": "target_feature", + "requirement": "required", + "data_type": "string" + }, + { + "name": "estimation_procedure", + "requirement": "required", + "data_type": "numeric" + }, + { + "name": "cost_matrix", + "data_type": "json" + }, + { + "name": "custom_testset", + "data_type": "json" + }, + { + "name": "evaluation_measures", + "data_type": "string" + } + ] + } + } + } + } + }, + "412": { + "description": "Precondition failed. An error code and message are returned.\\n240 - Please provide task type ID.\\n241 - Unknown task type. The task type with the given id was not found in the database\\n", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Error" + } + } + } + } + } + } + }, + "/user/list": { + "get": { + "tags": [ + "user" + ], + "summary": "List all users by user id", + "description": "Returns an array with all user ids and names.", + "operationId": "Api_user::username_list", + "responses": { + "200": { + "description": "A list of users", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UserList" + }, + "example": { + "users": { + "user": [ + { + "id": "1", + "username": "janvanrijn@gmail.com" + }, + { + "id": "2", + "username": "joaquin.vanschoren@gmail.com" + } + ] + } + } + } + } + } + } + } + } + }, + "components": { + "schemas": { + "inline_response_200_16_flow_untag": { + "properties": { + "id": { + "description": "ID of the untagged setup", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationMeasureList_evaluation_measures_measures": { + "properties": { + "measure": { + "description": "The evaluation measure names", + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "inline_response_200_10_flow_exists": { + "properties": { + "id": { + "description": "The id of the flow with the given name and (external) version", + "type": "string" + }, + "exists": { + "description": "true or false", + "type": "string" + } + }, + "type": "object" + }, + "Data_data_set_description": { + "properties": { + "default_target_attribute": { + "description": "For tabular data, the name of the column that is typically used as the target attribute for that data set", + "type": "string" + }, + "upload_date": { + "description": "The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss", + "type": "string" + }, + "version_label": { + "description": "The version of the dataset, as defined by the uploader, for reference. Can be any format as long as it is unique.", + "type": "string" + }, + "description": { + "description": "Wiki description of the dataset, in (Git flavoured) markdown format", + "type": "string" + }, + "format": { + "description": "Data format, for instance ARFF", + "type": "string" + }, + "url": { + "description": "The URL where the data can be downloaded", + "type": "string" + }, + "tag": { + "description": "Tags added by OpenML users. Includes study tags in the form `study_1`", + "type": "array", + "items": { + "type": "string" + } + }, + "visibility": { + "description": "Who can see the dataset. For instance `public`.", + "type": "string" + }, + "md5_checksum": { + "description": "Checksum to verify downloads of the dataset", + "type": "string" + }, + "version": { + "description": "The version of the dataset, set by OpenML. A positive integer", + "type": "string" + }, + "status": { + "description": "active, in_preparation, or deactivated", + "type": "string" + }, + "file_id": { + "description": "The ID of the dataset file stored on the OpenML server", + "type": "string" + }, + "licence": { + "description": "The licence granted for using the dataset, for instance Public or CC-BY", + "type": "string" + }, + "original_data_url": { + "description": "The URL where the original data is hosted.", + "type": "string" + }, + "id": { + "description": "ID of the dataset, a positive integer", + "type": "string" + }, + "name": { + "description": "The name of the dataset", + "type": "string" + } + }, + "type": "object" + }, + "DataList_data_dataset": { + "properties": { + "did": { + "description": "The dataset ID", + "type": "string" + }, + "status": { + "description": "The dataset status, either in_preparation, active, or deactivated", + "type": "string" + }, + "quality": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataList_data_quality" + } + }, + "name": { + "description": "The dataset name", + "type": "string" + }, + "format": { + "description": "The data format of the dataset, e.g. ARFF", + "type": "string" + } + }, + "type": "object" + }, + "Task_task_description_estimation_procedure": { + "properties": { + "parameter": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Task_task_description_estimation_procedure_parameter" + } + }, + "type": { + "description": "The type of procedure, e.g. crossvalidation", + "type": "string" + }, + "data_splits_url": { + "description": "The url where the data splits can be downloaded", + "type": "string" + } + }, + "type": "object" + }, + "DataList_data_quality": { + "properties": { + "name": { + "description": "The name of the property", + "type": "string" + }, + "value": { + "description": "The value of the property", + "type": "string" + } + }, + "type": "object" + }, + "FlowList_flows_flow": { + "properties": { + "full_name": { + "description": "The full flow name (name + internal version number)", + "type": "string" + }, + "external_version": { + "description": "The external flow version", + "type": "string" + }, + "version": { + "description": "The internal flow version", + "type": "string" + }, + "uploader": { + "description": "The ID of the person who uploaded the flow", + "type": "string" + }, + "id": { + "description": "The flow ID", + "type": "string" + }, + "name": { + "description": "The flow name", + "type": "string" + } + }, + "type": "object" + }, + "Run_run_description_input_data_dataset": { + "properties": { + "did": { + "description": "The id of the dataset", + "type": "string" + }, + "url": { + "description": "The download url of the dataset", + "type": "string" + }, + "name": { + "description": "The name of the dataset", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationList_evaluations": { + "properties": { + "evaluation": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EvaluationList_evaluations_evaluation" + } + } + }, + "type": "object" + }, + "inline_response_200_14_study_delete": { + "properties": { + "id": { + "description": "ID of the deleted setup, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "DataUnprocessed": { + "properties": { + "data_unprocessed": { + "$ref": "#/components/schemas/DataUnprocessed_data_unprocessed" + } + }, + "type": "object" + }, + "DataUnprocessed_data_unprocessed_dataset": { + "properties": { + "did": { + "description": "ID of the dataset a positive integer", + "type": "string" + }, + "status": { + "description": "Status of the dataset", + "type": "string" + }, + "version": { + "description": "Version of the dataset, a positive integer", + "type": "string" + }, + "name": { + "description": "The name of the dataset", + "type": "string" + }, + "format": { + "description": "The dataset format, e.g. ARFF", + "type": "string" + } + }, + "type": "object" + }, + "EstimationProcedureList_estimationprocedures": { + "properties": { + "estimationprocedure": { + "type": "array", + "items": { + "$ref": "#/components/schemas/EstimationProcedureList_estimationprocedures_estimationprocedure" + } + } + }, + "type": "object" + }, + "TaskTypeList": { + "properties": { + "task_types": { + "$ref": "#/components/schemas/TaskTypeList_task_types" + } + }, + "type": "object" + }, + "Run_run_description_output_data_evaluation": { + "properties": { + "array_data": { + "description": "For composite evaluation measures (e.g. per-class measures, confusion matrix), a string (JSON) representation of the evaluation.", + "type": "string" + }, + "name": { + "description": "The name of the evaluation measure", + "type": "string" + }, + "value": { + "description": "The result of the evaluation", + "type": "string" + }, + "flow_id": { + "description": "The id of the code used to compute this evaluation method", + "type": "string" + } + }, + "type": "object" + }, + "TaskList_task_quality": { + "properties": { + "name": { + "description": "The name of the quality", + "type": "string" + }, + "value": { + "description": "The value of the quality", + "type": "string" + } + }, + "type": "object" + }, + "Task_task_description": { + "properties": { + "input": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Task_task_description_input" + } + }, + "task_type": { + "description": "The type of the task, e.g. Supervised Classification", + "type": "string" + }, + "tag": { + "description": "Tags added by OpenML uers. Includes study tags in the form 'study_1'", + "type": "array", + "items": { + "type": "string" + } + }, + "task_id": { + "description": "ID of the task, a positive integer", + "type": "string" + }, + "output": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Task_task_description_output" + } + } + }, + "type": "object" + }, + "inline_response_200_9_upload_flow": { + "properties": { + "id": { + "description": "ID of the uploaded flow, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "Flow_flow_description": { + "properties": { + "upload_date": { + "description": "The datetime that the flow was uploaded, format yyyy-MM-dd HH:mm:ss", + "type": "string" + }, + "description": { + "description": "Wiki description of the flow, in (Git flavoured) markdown format", + "type": "string" + }, + "language": { + "description": "The programming language the flow is written in.", + "type": "string" + }, + "parameter": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Flow_flow_description_parameter" + } + }, + "tag": { + "description": "Tags added by OpenML users. Includes study tags in the form `study_1`", + "type": "array", + "items": { + "type": "string" + } + }, + "version": { + "description": "The version of the flow, set by OpenML. A positive integer", + "type": "string" + }, + "version_label": { + "description": "The version of the flow, as defined by the uploader, for reference. Can be any format as long as it is unique.", + "type": "string" + }, + "dependencies": { + "description": "The libraries that this flow depends on, and their version numbers.", + "type": "string" + }, + "uploader": { + "description": "The uploader of the flow", + "type": "string" + }, + "id": { + "description": "ID of the flow, a positive integer", + "type": "string" + }, + "name": { + "description": "The name of the flow", + "type": "string" + } + }, + "type": "object" + }, + "Task": { + "properties": { + "task_description": { + "$ref": "#/components/schemas/Task_task_description" + } + }, + "type": "object" + }, + "Setup": { + "properties": { + "setup_parameters": { + "$ref": "#/components/schemas/Setup_setup_parameters" + } + }, + "type": "object" + }, + "FlowList_flows": { + "properties": { + "flow": { + "type": "array", + "items": { + "$ref": "#/components/schemas/FlowList_flows_flow" + } + } + }, + "type": "object" + }, + "RunTrace": { + "properties": { + "trace": { + "$ref": "#/components/schemas/RunTrace_trace" + } + }, + "type": "object" + }, + "Task_task_description_predictions_feature": { + "properties": { + "type": { + "description": "The type of the prediction feature, e.g. integer", + "type": "string" + }, + "name": { + "description": "The name of the prediction feature, e.g. row_id", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_24_study_delete": { + "properties": { + "id": { + "description": "ID of the deleted study, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_5_upload_task": { + "properties": { + "id": { + "description": "ID of the uploaded task, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_13_flow_untag": { + "properties": { + "id": { + "description": "ID of the untagged flow", + "type": "string" + } + }, + "type": "object" + }, + "UserList_users": { + "properties": { + "user": { + "type": "array", + "items": { + "$ref": "#/components/schemas/UserList_users_user" + } + } + }, + "type": "object" + }, + "DataFeatures": { + "properties": { + "data_features": { + "$ref": "#/components/schemas/DataFeatures_data_features" + } + }, + "type": "object" + }, + "Task_task_description_predictions": { + "properties": { + "feature": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Task_task_description_predictions_feature" + } + }, + "format": { + "description": "The fromat of the predictions, e.g. ARFF", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_15_flow_tag": { + "properties": { + "id": { + "description": "ID of the tagged setup", + "type": "string" + } + }, + "type": "object" + }, + "Setup_setup_parameters": { + "properties": { + "parameter_setting": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Setup_setup_parameters_parameter_setting" + } + }, + "flow_id": { + "description": "ID of the flow, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "DataList": { + "properties": { + "data": { + "$ref": "#/components/schemas/DataList_data" + } + }, + "type": "object" + }, + "inline_response_200_26_study_attach": { + "properties": { + "linked_entities": { + "description": "The number of linked entities", + "type": "string" + }, + "main_entity_type": { + "description": "Main entity type of the of the study", + "type": "string" + }, + "id": { + "description": "ID of the study, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_2_data_tag": { + "properties": { + "id": { + "description": "ID of the tagged dataset", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_23_upload_flow": { + "properties": { + "id": { + "description": "ID of the run with the trace, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationRequest_evaluation_request": { + "properties": { + "run": { + "$ref": "#/components/schemas/EvaluationRequest_evaluation_request_run" + } + }, + "type": "object" + }, + "Run": { + "properties": { + "run_description": { + "$ref": "#/components/schemas/Run_run_description" + } + }, + "type": "object" + }, + "inline_response_200_6_task_tag": { + "properties": { + "id": { + "description": "ID of the tagged task", + "type": "string" + } + }, + "type": "object" + }, + "RunList": { + "properties": { + "runs": { + "$ref": "#/components/schemas/RunList_runs" + } + }, + "type": "object" + }, + "inline_response_200_17_data_delete": { + "properties": { + "id": { + "description": "ID of the deleted run, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "Task_task_description_input": { + "properties": { + "data_set": { + "$ref": "#/components/schemas/Task_task_description_data_set" + }, + "cost_matrix": { + "description": "The cost matrix, indicating the costs for each type of misclassification", + "type": "array", + "items": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + } + } + }, + "name": { + "description": "The name of the input, e.g. source_data", + "type": "string" + }, + "evaluation_measures": { + "$ref": "#/components/schemas/Task_task_description_evaluation_measures" + }, + "estimation_procedure": { + "$ref": "#/components/schemas/Task_task_description_estimation_procedure" + } + }, + "type": "object" + }, + "UserList": { + "properties": { + "users": { + "$ref": "#/components/schemas/UserList_users" + } + }, + "type": "object" + }, + "Study_study_runs": { + "properties": { + "run_id": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "DataFeatures_data_features_feature": { + "properties": { + "index": { + "description": "Feature index", + "type": "string" + }, + "name": { + "description": "Feature name", + "type": "string" + }, + "data_type": { + "description": "Feature data type", + "type": "string" + }, + "is_target": { + "description": "Whether this feature is seen as a target feature", + "type": "string" + }, + "is_ignore": { + "description": "Whether this feature should be ignored in modelling (e.g. every value is unique)", + "type": "string" + }, + "is_row_identifier": { + "description": "Whether this feature is a row identifier", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_21_upload_flow": { + "properties": { + "id": { + "description": "ID of the evaluated run, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "TaskType": { + "properties": { + "description": { + "description": "A description of the task type", + "type": "string" + }, + "date": { + "description": "The date when the task type was created", + "type": "string" + }, + "output": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskType_output" + } + }, + "contributor": { + "type": "array", + "items": { + "type": "string" + } + }, + "input": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskType_input" + } + }, + "id": { + "description": "ID of the task type, a positive integer", + "type": "string" + }, + "name": { + "description": "The name of the task type, e.g. Supervised Classification", + "type": "string" + } + }, + "type": "object" + }, + "Run_run_description_output_data_file": { + "properties": { + "did": { + "description": "The id of the uploaded file", + "type": "string" + }, + "file_id": { + "description": "The reference id of the uploaded file, for downloading afterward", + "type": "string" + }, + "name": { + "description": "The name of the uploaded file (e.g., description, predictions, model,...)", + "type": "string" + } + }, + "type": "object" + }, + "TaskType_input": { + "properties": { + "data_set": { + "$ref": "#/components/schemas/Task_task_description_data_set" + }, + "cost_matrix": { + "type": "array", + "items": { + "type": "array", + "items": { + "type": "integer", + "format": "int64" + } + } + }, + "name": { + "description": "The name of the input, e.g. source_data", + "type": "string" + }, + "evaluation_measures": { + "$ref": "#/components/schemas/Task_task_description_evaluation_measures" + }, + "estimation_procedure": { + "$ref": "#/components/schemas/Task_task_description_estimation_procedure" + } + }, + "type": "object" + }, + "Run_run_description_output_data": { + "properties": { + "evaluation": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Run_run_description_output_data_evaluation" + } + }, + "file": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Run_run_description_output_data_file" + } + } + }, + "type": "object" + }, + "inline_response_200_3_data_untag": { + "properties": { + "id": { + "description": "ID of the untagged dataset", + "type": "string" + } + }, + "type": "object" + }, + "Task_task_description_output": { + "properties": { + "name": { + "description": "The name of the output, e.g. predictions", + "type": "string" + }, + "predictions": { + "$ref": "#/components/schemas/Task_task_description_predictions" + } + }, + "type": "object" + }, + "DataQualityList": { + "properties": { + "data_qualities_list": { + "$ref": "#/components/schemas/DataQualityList_data_qualities_list" + } + }, + "type": "object" + }, + "DataUnprocessed_data_unprocessed": { + "properties": { + "dataset": { + "$ref": "#/components/schemas/DataUnprocessed_data_unprocessed_dataset" + } + }, + "type": "object" + }, + "Study": { + "properties": { + "study": { + "$ref": "#/components/schemas/Study_study" + } + }, + "type": "object" + }, + "DataList_data": { + "properties": { + "dataset": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataList_data_dataset" + } + } + }, + "type": "object" + }, + "UserList_users_user": { + "properties": { + "username": { + "description": "The full user name", + "type": "string" + }, + "id": { + "description": "The user ID", + "type": "string" + } + }, + "type": "object" + }, + "TaskType_output": { + "properties": { + "name": { + "description": "The name of the output, e.g. predictions", + "type": "string" + }, + "predictions": { + "$ref": "#/components/schemas/TaskType_predictions" + } + }, + "type": "object" + }, + "RunList_runs_run": { + "properties": { + "task_id": { + "description": "The ID of the task solved by this run", + "type": "string" + }, + "run_id": { + "description": "The run ID", + "type": "string" + }, + "error_message": { + "description": "Error message generated by the run (if any)", + "type": "string" + }, + "setup_id": { + "description": "Ignore (internal representation of the parameter setting)", + "type": "string" + }, + "uploader": { + "description": "The ID of the person uploading this run", + "type": "string" + }, + "flow_id": { + "description": "The ID of the flow used in this run", + "type": "string" + } + }, + "type": "object" + }, + "DataFeatures_data_features": { + "properties": { + "feature": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataFeatures_data_features_feature" + } + } + }, + "type": "object" + }, + "DataQualities_data_qualities_quality": { + "properties": { + "name": { + "description": "The name of the dataset quality measures", + "type": "string" + }, + "value": { + "description": "The value for this dataset", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_12_flow_tag": { + "properties": { + "id": { + "description": "ID of the tagged flow", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_8_flow_delete": { + "properties": { + "id": { + "description": "ID of the deleted flow, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "DataQualities_data_qualities": { + "properties": { + "quality": { + "type": "array", + "items": { + "$ref": "#/components/schemas/DataQualities_data_qualities_quality" + } + } + }, + "type": "object" + }, + "EvaluationRequest": { + "properties": { + "evaluation_request": { + "$ref": "#/components/schemas/EvaluationRequest_evaluation_request" + } + }, + "type": "object" + }, + "inline_response_200_18_upload_flow": { + "properties": { + "id": { + "description": "ID of the uploaded run, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "SetupList": { + "properties": { + "setups": { + "$ref": "#/components/schemas/SetupList_setups" + } + }, + "type": "object" + }, + "TaskList": { + "properties": { + "task": { + "$ref": "#/components/schemas/TaskList_task" + } + }, + "type": "object" + }, + "inline_response_200_4_task_delete": { + "properties": { + "id": { + "description": "ID of the deleted task, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "Task_task_description_data_set": { + "properties": { + "data_set_id": { + "description": "The id of the dataset", + "type": "string" + }, + "target_feature": { + "description": "The name of the target feature for this task", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationList": { + "properties": { + "evaluations": { + "$ref": "#/components/schemas/EvaluationList_evaluations" + } + }, + "type": "object" + }, + "Run_run_description": { + "properties": { + "setup_string": { + "description": "Configuration of the flow as a string, to be interpreted by the flow, its library, or command line interface.", + "type": "string" + }, + "task_type": { + "description": "The type of task solved by this run (e.g., classification)", + "type": "string" + }, + "task_id": { + "description": "The id of the task solved by this run", + "type": "string" + }, + "task_evaluation_measure": { + "description": "The evaluation measure that is supposed to be optimized in the task, if any", + "type": "string" + }, + "uploader_name": { + "description": "The name of the uploader of the run", + "type": "string" + }, + "input_data": { + "$ref": "#/components/schemas/Run_run_description_input_data" + }, + "tag": { + "description": "Tags added by OpenML users. Includes study tags in the form `study_1`", + "type": "array", + "items": { + "type": "string" + } + }, + "output_data": { + "$ref": "#/components/schemas/Run_run_description_output_data" + }, + "uploader": { + "description": "The uploader of the run", + "type": "string" + }, + "flow_id": { + "description": "The id of the flow used in this run", + "type": "string" + }, + "flow_name": { + "description": "The name of the flow used in this run", + "type": "string" + }, + "id": { + "description": "ID of the run, a positive integer", + "type": "string" + }, + "parameter_setting": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Run_run_description_parameter_setting" + } + } + }, + "type": "object" + }, + "FlowList": { + "properties": { + "flows": { + "$ref": "#/components/schemas/FlowList_flows" + } + }, + "type": "object" + }, + "inline_response_200_19_run_tag": { + "properties": { + "id": { + "description": "ID of the tagged run", + "type": "string" + } + }, + "type": "object" + }, + "Study_study_data": { + "properties": { + "data_id": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "inline_response_200_data_delete": { + "properties": { + "id": { + "description": "ID of the deleted dataset, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "RunTrace_trace": { + "properties": { + "trace_iteration": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RunTrace_trace_trace_iteration" + } + }, + "run_id": { + "description": "run ID", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_7_task_untag": { + "properties": { + "id": { + "description": "ID of the untagged task", + "type": "string" + } + }, + "type": "object" + }, + "Data": { + "properties": { + "data_set_description": { + "$ref": "#/components/schemas/Data_data_set_description" + } + }, + "type": "object" + }, + "Task_task_description_evaluation_measures": { + "properties": { + "evaluation_measure": { + "description": "The evaluation measure to optimize in this task", + "type": "string" + } + }, + "type": "object" + }, + "SetupList_setups_parameter": { + "properties": { + "default_value": { + "description": "The parameter's default value", + "type": "string" + }, + "data_type": { + "description": "The parameter's data type", + "type": "string" + }, + "value": { + "description": "The parameter value in this setup", + "type": "string" + }, + "parameter_name": { + "description": "The parameter's short name", + "type": "string" + }, + "full_name": { + "description": "The parameter's full name", + "type": "string" + }, + "flow_id": { + "description": "The (sub)flow ID", + "type": "string" + }, + "flow_name": { + "description": "The (sub)flow name", + "type": "string" + }, + "id": { + "description": "The parameter ID", + "type": "string" + } + }, + "type": "object" + }, + "TaskList_task_input": { + "properties": { + "name": { + "description": "The name of the input", + "type": "string" + }, + "value": { + "description": "The value of the input", + "type": "string" + } + }, + "type": "object" + }, + "StudyList_study_list": { + "properties": { + "study": { + "type": "array", + "items": { + "$ref": "#/components/schemas/StudyList_study_list_study" + } + } + }, + "type": "object" + }, + "Study_study_tag": { + "properties": { + "write_access": { + "description": "The write access level of the study (e.g. public)", + "type": "string" + }, + "name": { + "description": "The name of the study (e.g. study_1)", + "type": "string" + } + }, + "type": "object" + }, + "Flow": { + "properties": { + "flow_description": { + "$ref": "#/components/schemas/Flow_flow_description" + } + }, + "type": "object" + }, + "Run_run_description_parameter_setting": { + "properties": { + "name": { + "description": "The name of the parameter", + "type": "string" + }, + "value": { + "description": "The value of the parameter used", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationRequest_evaluation_request_run": { + "properties": { + "setup_id": { + "description": "ID of the setup, a positive integer", + "type": "string" + }, + "upload_time": { + "description": "The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss", + "type": "string" + }, + "uploader": { + "description": "ID of the uploader, a positive integer", + "type": "string" + }, + "task_id": { + "description": "ID of the task, a positive integer", + "type": "string" + }, + "run_id": { + "description": "ID of the run, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "Error": { + "properties": { + "message": { + "type": "string" + }, + "code": { + "type": "integer" + }, + "additional_message": { + "type": "string" + } + }, + "type": "object" + }, + "EstimationProcedureList_estimationprocedures_estimationprocedure": { + "properties": { + "name": { + "description": "The estimation procedure name, e.g. '10 fold Crossvalidation'", + "type": "string" + }, + "folds": { + "description": "The number of cross-validation folds, e.g. '10'", + "type": "string" + }, + "stratified_sampling": { + "description": "Whether or not the sampling is stratified, 'true' or 'false'", + "type": "string" + }, + "ttid": { + "description": "The task type ID", + "type": "string" + }, + "repeats": { + "description": "The number of repeats, e.g. '10'", + "type": "string" + }, + "type": { + "description": "The estimation procedure type, e.g. 'crossvalidation'", + "type": "string" + }, + "id": { + "description": "The estimation procedure ID", + "type": "string" + } + }, + "type": "object" + }, + "TaskTypeList_task_types": { + "properties": { + "task_type": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskTypeList_task_types_task_type" + } + } + }, + "type": "object" + }, + "TaskList_task_task": { + "properties": { + "status": { + "description": "The status of the source dataset, active, in_preparation, or deactivated", + "type": "string" + }, + "task_type": { + "description": "The type of task (e.g. Supervised Classificationr)", + "type": "string" + }, + "name": { + "description": "The name of the source dataset", + "type": "string" + }, + "task_id": { + "description": "The ID of the task", + "type": "string" + }, + "format": { + "description": "The format of the source dataset", + "type": "string" + }, + "did": { + "description": "The id of the source dataset", + "type": "string" + }, + "tag": { + "type": "array", + "items": { + "type": "string" + } + }, + "input": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskList_task_input" + } + }, + "quality": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskList_task_quality" + } + } + }, + "type": "object" + }, + "inline_response_200_20_run_untag": { + "properties": { + "id": { + "description": "ID of the untagged run", + "type": "string" + } + }, + "type": "object" + }, + "StudyList": { + "properties": { + "study_list": { + "$ref": "#/components/schemas/StudyList_study_list" + } + }, + "type": "object" + }, + "Study_study": { + "properties": { + "runs": { + "$ref": "#/components/schemas/Study_study_runs" + }, + "tasks": { + "$ref": "#/components/schemas/Study_study_tasks" + }, + "name": { + "description": "The name of the study", + "type": "string" + }, + "creator": { + "description": "A comma-separated list of the study creators", + "type": "string" + }, + "flows": { + "$ref": "#/components/schemas/Study_study_flows" + }, + "creation_date": { + "description": "The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss", + "type": "string" + }, + "alias": { + "description": "The alias of the study", + "type": "string" + }, + "tag": { + "$ref": "#/components/schemas/Study_study_tag" + }, + "main_entity_type": { + "description": "The type of entity collected in the study (e.g. task or run)", + "type": "string" + }, + "data": { + "$ref": "#/components/schemas/Study_study_data" + }, + "id": { + "description": "The ID of the study", + "type": "string" + } + }, + "type": "object" + }, + "inline_response_200_25_upload_study": { + "properties": { + "id": { + "description": "ID of the uploaded study, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationList_evaluations_evaluation": { + "properties": { + "function": { + "description": "The name of the evaluation function", + "type": "string" + }, + "task_id": { + "description": "The ID of the tasks solved by this run", + "type": "string" + }, + "run_id": { + "description": "The run ID", + "type": "string" + }, + "array_data": { + "description": "For structured evaluation measures, an array of evaluation values (e.g. per-class predictions, evaluation matrices,...)", + "type": "string" + }, + "value": { + "description": "The outcome of the evaluation", + "type": "string" + }, + "flow_id": { + "description": "The ID of the flow used by this run", + "type": "string" + } + }, + "type": "object" + }, + "EstimationProcedureList": { + "properties": { + "estimationprocedures": { + "$ref": "#/components/schemas/EstimationProcedureList_estimationprocedures" + } + }, + "type": "object" + }, + "DataQualityList_data_qualities_list": { + "properties": { + "quality": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "Study_study_flows": { + "properties": { + "flow_id": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "StudyList_study_list_study": { + "properties": { + "alias": { + "description": "The alias of the study", + "type": "string" + }, + "creation_date": { + "description": "The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss", + "type": "string" + }, + "creator": { + "description": "A comma-separated list of the study creators", + "type": "string" + }, + "id": { + "description": "The ID of the study", + "type": "string" + }, + "name": { + "description": "The name of the study", + "type": "string" + } + }, + "type": "object" + }, + "Run_run_description_input_data": { + "properties": { + "dataset": { + "$ref": "#/components/schemas/Run_run_description_input_data_dataset" + } + }, + "type": "object" + }, + "TaskTypeList_task_types_task_type": { + "properties": { + "description": { + "description": "A description of the task type", + "type": "string" + }, + "creator": { + "description": "A comma-separated list of the task type creators", + "type": "string" + }, + "id": { + "description": "The ID of the task type", + "type": "string" + }, + "name": { + "description": "The name of the task type", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationMeasureList_evaluation_measures": { + "properties": { + "measures": { + "$ref": "#/components/schemas/EvaluationMeasureList_evaluation_measures_measures" + } + }, + "type": "object" + }, + "TaskType_predictions": { + "properties": { + "feature": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Task_task_description_predictions_feature" + } + }, + "format": { + "description": "The format of the predictions, e.g. ARFF", + "type": "string" + } + }, + "type": "object" + }, + "Flow_flow_description_parameter": { + "properties": { + "default_value": { + "description": "The default value of the parameter", + "type": "string" + }, + "name": { + "description": "The name of the parameter", + "type": "string" + }, + "data_type": { + "description": "The data type of the parameter", + "type": "string" + }, + "description": { + "description": "A description of the parameter", + "type": "string" + } + }, + "type": "object" + }, + "RunTrace_trace_trace_iteration": { + "properties": { + "setup_string": { + "description": "A JSON representation of the setup (configuration)", + "type": "string" + }, + "repeat": { + "description": "The number of the repeat in the outer cross-valudation", + "type": "string" + }, + "selected": { + "description": "Whether this setup was selected as the best one (true or false)", + "type": "string" + }, + "iteration": { + "description": "A number of the optimization iteration", + "type": "string" + }, + "fold": { + "description": "The number of the fold in the inner cross-validation", + "type": "string" + }, + "evaluation": { + "description": "The evaluation score of the setup", + "type": "string" + } + }, + "type": "object" + }, + "EvaluationMeasureList": { + "properties": { + "evaluation_measures": { + "$ref": "#/components/schemas/EvaluationMeasureList_evaluation_measures" + } + }, + "type": "object" + }, + "SetupList_setups": { + "properties": { + "setup": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SetupList_setups_setup" + } + } + }, + "type": "object" + }, + "TaskList_task": { + "properties": { + "task": { + "type": "array", + "items": { + "$ref": "#/components/schemas/TaskList_task_task" + } + } + }, + "type": "object" + }, + "SetupList_setups_setup": { + "properties": { + "setup_id": { + "description": "The setup ID", + "type": "string" + }, + "parameter": { + "type": "array", + "items": { + "$ref": "#/components/schemas/SetupList_setups_parameter" + } + }, + "flow_id": { + "description": "The ID of the flow used by this run", + "type": "string" + } + }, + "type": "object" + }, + "Task_task_description_estimation_procedure_parameter": { + "properties": { + "name": { + "description": "The name of the parameter", + "type": "string" + }, + "value": { + "description": "The value of the parameter", + "type": "string" + } + }, + "type": "object" + }, + "RunList_runs": { + "properties": { + "run": { + "type": "array", + "items": { + "$ref": "#/components/schemas/RunList_runs_run" + } + } + }, + "type": "object" + }, + "Study_study_tasks": { + "properties": { + "task_id": { + "type": "array", + "items": { + "type": "string" + } + } + }, + "type": "object" + }, + "inline_response_200_1_upload_data_set": { + "properties": { + "id": { + "description": "ID of the uploaded dataset, a positive integer", + "type": "string" + } + }, + "type": "object" + }, + "Setup_setup_parameters_parameter_setting": { + "properties": { + "default_value": { + "description": "The default value of the parameter used", + "type": "string" + }, + "value": { + "description": "The value of the parameter used", + "type": "string" + }, + "data_type": { + "description": "The data type of the hyperparameter value", + "type": "string" + }, + "full_name": { + "description": "The full name of the hyperparameter", + "type": "string" + }, + "parameter_name": { + "description": "The short name of the hyperparameter", + "type": "string" + } + }, + "type": "object" + }, + "DataQualities": { + "properties": { + "data_qualities": { + "$ref": "#/components/schemas/DataQualities_data_qualities" + } + }, + "type": "object" + } + } + } +} \ No newline at end of file diff --git a/openapi/swagger.yaml b/openapi/swagger.yaml new file mode 100644 index 000000000..3c86cfc16 --- /dev/null +++ b/openapi/swagger.yaml @@ -0,0 +1,3338 @@ +openapi: 3.0.0 +info: + title: 'OpenML API' + description: 'REST API for sharing, organizing and reusing machine learning datasets, code, and experiments. Follows a predictive URL scheme from endpoint https://www.openml.org/api/v1/json (or /xml). You need to add your api_key for every call except GET calls. The API key can be found in your profile on openml.org.' + version: 1.0.0 +servers: + - + url: 'https://openml.org/api/v1/json' + description: 'The current OpenML API' + - + url: 'https://test.openml.org/api/v1/json' + description: 'The test OpenML API' +paths: + /data/tag: + post: + tags: + - data + summary: 'Tag a dataset' + description: 'Tags a dataset.' + operationId: 'Api_data::data_tag' + parameters: + - + name: data_id + in: query + description: 'Id of the dataset.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the tagged dataset' + content: + application/json: + schema: + properties: + data_tag: { $ref: '#/components/schemas/inline_response_200_2_data_tag' } + type: object + example: + data_tag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /data/untag: + post: + tags: + - data + summary: 'Untag a dataset' + description: 'Untags a dataset.' + operationId: 'Api_data::data_untag' + parameters: + - + name: data_id + in: query + description: 'Id of the dataset.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The ID of the untagged dataset' + content: + application/json: + schema: + properties: + data_untag: { $ref: '#/components/schemas/inline_response_200_3_data_untag' } + type: object + example: + data_untag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/data/list/{filters}': + get: + tags: + - data + summary: 'List and filter datasets' + description: 'List datasets, possibly filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form ''/data/list/{filter}/{value}/{filter}/{value}/...'' Returns an array with all datasets that match the constraints.' + operationId: 'Api_data::data_list' + parameters: + - + name: filters + in: path + description: "Any combination of these filters\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n /status/{status} - returns only datasets with a given status, either 'active', 'deactivated', or 'in_preparation'.\r\n /tag/{tag} - returns only datasets tagged with the given tag.\r\n /{data_quality}/{range} - returns only tasks for which the underlying datasets have certain qualities. {data_quality} can be data_id, data_name, data_version, number_instances, number_features, number_classes, number_missing_values. {range} can be a specific value or a range in the form 'low..high'. Multiple qualities can be combined, as in 'number_instances/0..50/number_features/0..10'.\r\n " + required: true + schema: + type: string + responses: + '200': + description: 'A list of datasets with the given task' + content: + application/json: + schema: + $ref: '#/components/schemas/DataList' + example: + data: + dataset: [{ did: '1', name: anneal, status: active, format: ARFF, quality: [{ name: MajorityClassSize, value: '684' }, { name: MaxNominalAttDistinctValues, value: '10.0' }, { name: MinorityClassSize, value: '0' }, { name: NumBinaryAtts, value: '14.0' }, { name: NumberOfClasses, value: '6' }, { name: NumberOfFeatures, value: '39' }, { name: NumberOfInstances, value: '898' }, { name: NumberOfInstancesWithMissingValues, value: '0' }, { name: NumberOfMissingValues, value: '0' }, { name: NumberOfNumericFeatures, value: '6' }, { name: NumberOfSymbolicFeatures, value: '32' }] }] + '412': + description: 'Precondition failed. An error code and message are returned.\n370 - Illegal filter specified.\n371 - Filter values/ranges not properly specified.\n372 - No results. There where no matches for the given constraints.\n373 - Can not specify an offset without a limit.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/data/{id}': + get: + tags: + - data + summary: 'Get dataset description' + description: 'Returns information about a dataset. The information includes the name, information about the creator, URL to download it and more.' + operationId: 'Api_data::data' + parameters: + - + name: id + in: path + description: 'Id of the dataset.' + required: true + schema: + type: integer + responses: + '200': + description: 'A dataset description' + content: + application/json: + schema: + $ref: '#/components/schemas/Data' + example: + data_set_description: + id: '1' + name: anneal + version: '2' + description: ... + format: ARFF + upload_date: '2014-04-06 23:19:20' + licence: Public + url: 'https://www.openml.org/data/download/1/dataset_1_anneal.arff' + file_id: '1' + default_target_attribute: class + version_label: '2' + tag: [study_1, uci] + visibility: public + original_data_url: 'https://www.openml.org/d/2' + status: active + md5_checksum: d01f6ccd68c88b749b20bbe897de3713 + '412': + description: 'Precondition failed. An error code and message are returned\n110 - Please provide data_id.\n111 - Unknown dataset. Data set description with data_id was not found in the database.\n112 - No access granted. This dataset is not shared with you.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + delete: + tags: + - data + summary: 'Delete dataset' + description: 'Deletes a dataset. Upon success, it returns the ID of the deleted dataset.' + operationId: 'Api_data::data_delete' + parameters: + - + name: id + in: path + description: 'Id of the dataset.' + required: true + schema: + type: integer + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'ID of the deleted dataset' + content: + application/json: + schema: + properties: + data_delete: { $ref: '#/components/schemas/inline_response_200_data_delete' } + type: object + example: + data_delete: + id: '4328' + '412': + description: 'Precondition failed. An error code and message are returned\n- 350 - Please provide API key. In order to remove your content, please authenticate.\n- 351 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n- 352 - Dataset does not exists. The data ID could not be linked to an existing dataset.\n- 353 - Dataset is not owned by you. The dataset is owned by another user. Hence you cannot delete it.\n- 354 - Dataset is in use by other content. Can not be deleted. The data is used in tasks or runs. Delete other content before deleting this dataset.\n- 355 - Deleting dataset failed. Deleting the dataset failed. Please contact support team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /data: + post: + tags: + - data + summary: 'Upload dataset' + description: 'Uploads a dataset. Upon success, it returns the data id.' + operationId: 'Api_data::data_upload' + parameters: + - + name: description + in: query + description: 'An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/data).' + required: true + schema: + type: file + - + name: dataset + in: query + description: 'The actual dataset, being an ARFF file.' + required: true + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the uploaded dataset' + content: + application/json: + schema: + properties: + upload_data_set: { $ref: '#/components/schemas/inline_response_200_1_upload_data_set' } + type: object + example: + upload_data_set: + id: '4328' + '412': + description: 'Precondition failed. An error code and message are returned.\n130 - Problem with file uploading. There was a problem with the file upload.\n131 - Problem validating uploaded description file. The XML description format does not meet the standards.\n132 - Failed to move the files. Internal server error, please contact API administrators.\n133 - Failed to make checksum of datafile. Internal server error, please contact API administrators.\n134 - Failed to insert record in database. Internal server error, please contact API administrators.\n135 - Please provide description xml.\n136 - File failed format verification. The uploaded file is not valid according to the selected file format. Please check the file format specification and try again.\n137 - Please provide API key. In order to share content, please log in or provide your API key.\n138 - Authentication failed. The API key was not valid. Please try to login again, or contact API administrators\n139 - Combination name / version already exists. Leave version out for auto increment\n140 - Both dataset file and dataset url provided. The system is confused since both a dataset file (post) and a dataset url (xml) are provided. Please remove one.\n141 - Neither dataset file or dataset url are provided. Please provide either a dataset file as POST variable, or a dataset url in the description XML.\n142 - Error in processing arff file. Can be a syntax error, or the specified target feature does not exists. For now, we only check on arff files. If a dataset is claimed to be in such a format, and it can not be parsed, this error is returned.\n143 - Suggested target feature not legal. It is possible to suggest a default target feature (for predictive tasks). However, it should be provided in the data.\n144 - Unable to update dataset. The dataset with id could not be found in the database. If you upload a new dataset, unset the id.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /data/status/update/: + post: + tags: + - data + summary: 'Change the status of a dataset' + description: 'Change the status of a dataset, either ''active'' or ''deactivated''' + operationId: 'Api_data::status_update' + parameters: + - + name: data_id + in: query + description: 'Id of the dataset.' + required: true + schema: + type: integer + - + name: status + in: query + description: 'The status on which to filter the results, either ''active'' or ''deactivated''.' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '412': + description: 'Precondition failed. An error code and message are returned.\n691 - Illegal status\n692 - Dataset does not exists\n693 - Dataset is not owned by you\n694 - Illegal status transition\n695 - Status update failed\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/data/features/{id}': + get: + tags: + - data + summary: 'Get data features' + description: 'Returns the features of a dataset.' + operationId: 'Api_data::data_features' + parameters: + - + name: id + in: path + description: 'Id of the dataset.' + required: true + schema: + type: integer + responses: + '200': + description: 'All the features of the dataset' + content: + application/json: + schema: + $ref: '#/components/schemas/DataFeatures' + example: + data_features: + feature: [{ index: '0', name: sepallength, data_type: numeric, is_target: 'false', is_ignore: 'false', is_row_identifier: 'false' }, { index: '1', name: sepalwidth, data_type: numeric, is_target: 'false', is_ignore: 'false', is_row_identifier: 'false' }, { index: '2', name: petallength, data_type: numeric, is_target: 'false', is_ignore: 'false', is_row_identifier: 'false' }, { index: '3', name: petalwidth, data_type: numeric, is_target: 'false', is_ignore: 'false', is_row_identifier: 'false' }, { index: '4', name: class, data_type: nominal, is_target: 'true', is_ignore: 'false', is_row_identifier: 'false' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n270 - Please provide dataset ID.\n271 - Unknown dataset. Data set with the given data ID was not found (or is not shared with you).\n272 - No features found. The dataset did not contain any features, or we could not extract them.\n273 - Dataset not processed yet. The dataset was not processed yet, features are not yet available. Please wait for a few minutes.\n274 - Dataset processed with error. The feature extractor has run into an error while processing the dataset. Please check whether it is a valid supported file. If so, please contact the API admins.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /data/features: + post: + tags: + - data + summary: 'Upload dataset feature description' + description: 'Uploads dataset feature description. Upon success, it returns the data id.' + operationId: 'Api_data::data_features_upload' + parameters: + - + name: description + in: query + description: 'An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.features) and an [XML example](https://www.openml.org/api/v1/xml_example/data.features).' + required: true + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '412': + description: 'Precondition failed. An error code and message are returned.\n431 - Dataset already processed\n432 - Please provide description xml\n433 - Problem validating uploaded description file\n434 - Could not find dataset\n436 - Something wrong with XML, check data id and evaluation engine id\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /data/qualities/list: + get: + tags: + - data + summary: 'List all data qualities' + description: 'Returns a list of all data qualities in the system.' + operationId: 'Api_data::data_qualities_list' + responses: + '200': + description: 'A list of data qualities' + content: + application/json: + schema: + $ref: '#/components/schemas/DataQualityList' + example: + data_qualities_list: + quality: [NumberOfClasses, NumberOfFeatures, NumberOfInstances, NumberOfInstancesWithMissingValues, NumberOfMissingValues, NumberOfNumericFeatures, NumberOfSymbolicFeatures] + '412': + description: 'Precondition failed. An error code and message are returned\n370 - No data qualities available. There are no data qualities in the system.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/data/qualities/{id}': + get: + tags: + - data + summary: 'Get data qualities' + description: 'Returns the qualities of a dataset.' + operationId: 'Api_data::data_qualities' + parameters: + - + name: id + in: path + description: 'Id of the dataset.' + required: true + schema: + type: integer + responses: + '200': + description: 'All the qualities of the dataset' + content: + application/json: + schema: + $ref: '#/components/schemas/DataQualities' + example: + data_qualities: + quality: [{ name: ClassCount, value: '3.0' }, { name: ClassEntropy, value: '1.584962500721156' }, { name: NumberOfClasses, value: '3' }, { name: NumberOfFeatures, value: '5' }, { name: NumberOfInstances, value: '150' }, { name: NumberOfInstancesWithMissingValues, value: '0' }, { name: NumberOfMissingValues, value: '0' }, { name: NumberOfNumericFeatures, value: '4' }, { name: NumberOfSymbolicFeatures, value: '0' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n360 - Please provide data set ID\n361 - Unknown dataset. The data set with the given ID was not found in the database, or is not shared with you.\n362 - No qualities found. The registered dataset did not contain any calculated qualities.\n363 - Dataset not processed yet. The dataset was not processed yet, no qualities are available. Please wait for a few minutes.\n364 - Dataset processed with error. The quality calculator has run into an error while processing the dataset. Please check whether it is a valid supported file. If so, contact the support team.\n365 - Interval start or end illegal. There was a problem with the interval\nstart or end.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /data/qualities: + post: + tags: + - data + summary: 'Upload dataset qualities' + description: 'Uploads dataset qualities. Upon success, it returns the data id.' + operationId: 'Api_data::data_qualities_upload' + parameters: + - + name: description + in: query + description: 'An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.qualities) and an [XML example](https://www.openml.org/api/v1/xml_example/data.qualities).' + required: true + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '412': + description: 'Precondition failed. An error code and message are returned.\n381 - Something wrong with XML, please check did and evaluation_engine_id\n382 - Please provide description xml\n383 - Problem validating uploaded description file\n384 - Dataset not processed yet\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/data/unprocessed/{data_engine_id}/{order}': + get: + tags: + - data + summary: 'Get a list of unprocessed datasets' + description: 'This call is for people running their own dataset processing engines. It returns the details of datasets that are not yet processed by the given processing engine. It doesn''t process the datasets, it just returns the dataset info.' + operationId: 'Api_data::data_unprocessed' + parameters: + - + name: data_engine_id + in: path + description: 'The ID of the data processing engine. You get this ID when you register a new data processing engine with OpenML. The ID of the main data processing engine is 1.' + required: true + schema: + type: integer + - + name: order + in: path + description: 'When there are multiple datasets still to process, this defines which ones to return. Options are ''normal'' - the oldest datasets, or ''random''.' + required: true + schema: + type: string + responses: + '200': + description: 'A list of unprocessed datasets' + content: + application/json: + schema: + $ref: '#/components/schemas/DataUnprocessed' + example: + data_unprocessed: + run: [{ did: '1', status: deactivated, version: '2', name: anneal, format: ARFF }] + '412': + description: 'Precondition failed. An error code and message are returned.\n681 - No unprocessed datasets.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/data/qualities/unprocessed/{data_engine_id}/{order}': + post: + tags: + - data + summary: 'Get a list of datasets with unprocessed qualities' + description: 'This call is for people running their own dataset processing engines. It returns the details of datasets for which certain qualities are not yet processed by the given processing engine. It doesn''t process the datasets, it just returns the dataset info.' + operationId: 'Api_data::dataqualities_unprocessed' + parameters: + - + name: data_engine_id + in: path + description: 'The ID of the data processing engine. You get this ID when you register a new data processing engine with OpenML. The ID of the main data processing engine is 1.' + required: true + schema: + type: string + - + name: order + in: path + description: 'When there are multiple datasets still to process, this defines which ones to return. Options are ''normal'' - the oldest datasets, or ''random''.' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'API key to authenticate the user' + required: false + schema: + type: string + - + name: qualities + in: query + description: 'Comma-separated list of (at least two) quality names, e.g. ''NumberOfInstances,NumberOfFeatures''.' + required: true + schema: + type: string + responses: + '200': + description: 'A list of unprocessed datasets' + content: + application/json: + schema: + $ref: '#/components/schemas/DataUnprocessed' + example: + data_unprocessed: + run: [{ did: '1', status: deactivated, version: '2', name: anneal, format: ARFF }] + '412': + description: 'Precondition failed. An error code and message are returned.\n686 - Please specify the features the evaluation engine wants to calculate (at least 2).\n687 - No unprocessed datasets according to the given set of meta-features.\n688 - Illegal qualities.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /estimationprocedure/list: + get: + tags: + - estimationprocedure + summary: 'List all estimation procedures' + description: 'Returns an array with all model performance estimation procedures in the system.' + operationId: 'Api_estimationprocedure::estimationprocedure_list' + responses: + '200': + description: 'A list of estimation procedures' + content: + application/json: + schema: + $ref: '#/components/schemas/EstimationProcedureList' + example: + estimationprocedures: + estimationprocedure: [{ id: '1', ttid: '1', name: '10-fold Crossvalidation', type: crossvalidation, repeats: '1', folds: '10', stratified_sampling: 'true' }, { id: '2', ttid: '1', name: '5 times 2-fold Crossvalidation', type: crossvalidation, repeats: '5', folds: '2', stratified_sampling: 'true' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n500 - No model performance estimation procedures available.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/evaluation/request/{evaluation_engine_id}/{order}': + get: + tags: + - evaluation + summary: 'Get an unevaluated run' + description: 'This call is for people running their own evaluation engines. It returns the details of a run that is not yet evaluated by the given evaluation engine. It doesn''t evaluate the run, it just returns the run info.' + operationId: 'Api_evaluation::evaluation_request' + parameters: + - + name: evaluation_engine_id + in: path + description: 'The ID of the evaluation engine. You get this ID when you register a new evaluation engine with OpenML. The ID of the main evaluation engine is 1.' + required: true + schema: + type: string + - + name: order + in: path + description: 'When there are multiple runs still to evaluate, this defines which one to return. Options are ''normal'' - the oldest run, ''reverse'' - the newest run, or ''random'' - a random run.' + required: true + schema: + type: string + responses: + '200': + description: 'A list of evaluations descriptions' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationRequest' + example: + evaluation_request: + run: [{ setup_id: '68799271', upload_time: '2018-04-03 21:05:38', uploader: '1935', task_id: '3021', run_id: '8943712' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n100 - Function not valid.\n545 - No unevaluated runs according to the criteria.\n546 - Illegal filter.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/evaluation/list/{filters}': + get: + tags: + - evaluation + summary: 'List and filter evaluations' + description: 'List evaluations, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form ''/evaluation/list/{filter}/{value}/{filter}/{value}/...'' Returns an array with all evaluations that match the constraints. A maximum of 10,000 results are returned, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain tasks, flows, setups, uploaders or runs.' + operationId: 'Api_evaluation::evaluation_list' + parameters: + - + name: filters + in: path + description: "Any combination of these filters\r\n /function/{name} - name of the evaluation measure, e.g. area_under_auc or predictive_accuracy. See the OpenML website for the complete list of measures.\r\n /tag/{tag} - returns only evaluations of runs tagged with the given tag.\r\n /run/{ids} - return only evaluations for specific runs, specified as a comma-separated list of run IDs, e.g. ''1,2,3''\r\n /task/{ids} - return only evaluations for specific tasks, specified as a comma-separated list of task IDs, e.g. ''1,2,3''\r\n /flow/{ids} - return only evaluations for specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3''\r\n /setup/{ids} - return only evaluations for specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3''\r\n /uploader/{ids} - return only evaluations uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n /per_fold/{true,false} - whether or not to return crossvalidation scores per fold. Defaults to 'false'. Setting it to 'true' leads to large numbers of results, use only for very specific sets of runs.\r\n /sort_order/{asc,desc} - sorts the results by the evaluation value, according to the selected evaluation measure (function)\r\n " + required: true + schema: + type: string + responses: + '200': + description: 'A list of evaluations descriptions' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationList' + example: + evaluations: + evaluation: [{ function: area_under_roc_curve, upload_time: '2014-04-06 23:30:40', task_id: '68', run_id: '1', array_data: '[0,0.99113,0.898048,0.874862,0.791282,0.807343,0.820674]', value: '0.839359', uploader: '1', flow_id: '61' }, { function: f_measure, upload_time: '2014-04-06 23:30:40', task_id: '68', run_id: '1', array_data: '[0,0,0.711934,0.735714,0.601363,0.435678,0.430913]', value: '0.600026', uploader: '1', flow_id: '61' }, { function: predictive_accuracy, upload_time: '2014-04-06 23:30:40', task_id: '68', run_id: '1', array_data: [], value: '0.614634', uploader: '1', flow_id: '61' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n540 - Please provide at least task, flow or setup, uploader or run, to\nfilter results, or limit the number of responses.\n541 - The input parameters (task_id, setup_id, flow_id, run_id, uploader_id) did not meet the constraints (comma separated list of integers).\n542 - There where no results. Check whether there are runs under the given constraint.\n543 - Too many results. Given the constraints, there were still too many results. Please add filters to narrow down the list.\n544 - Illegal filter specified.\n545 - Offset specified without limit.\n546 - Requested result limit too high.\n547 - Per fold can only be set to value ''true'' or ''false''.\n548 - Per fold queries are experimental and require a fair amount of filters on resulting run records to keep the query fast (use, e.g., flow, setup, task and uploader filter)\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /evaluationmeasure/list: + get: + tags: + - evaluationmeasure + summary: 'List all evaluation measures' + description: 'Returns an array with all model evaluation measures in the system.' + operationId: 'Api_evaluationmeasure::evaluationmeasure_list' + responses: + '200': + description: 'A list of evaluation measures' + content: + application/json: + schema: + $ref: '#/components/schemas/EvaluationMeasureList' + example: + evaluation_measures: + measures: { measure: [area_under_roc_curve, average_cost, binominal_test, build_cpu_time] } + '/flow/list/{filters}': + get: + tags: + - flow + summary: 'List and filter flows' + description: 'List flows, possibly filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form ''/task/list/{filter}/{value}/{filter}/{value}/...'' Returns an array with all flows that match the constraints.' + operationId: 'Api_flow::flow_list' + parameters: + - + name: filters + in: path + description: "Any combination of these filters\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, tasks 11..15 will be returned. Both limit and offset need to be specified.\r\n /tag/{tag} - returns only tasks tagged with the given tag.\r\n /uploader/{id} - return only evaluations uploaded by a specific user, specified by user ID.\r\n " + required: true + schema: + type: string + responses: + '200': + description: 'A list of flows' + content: + application/json: + schema: + $ref: '#/components/schemas/FlowList' + example: + flows: + flow: [{ id: '65', full_name: weka.RandomForest(1), name: weka.RandomForest, version: '1', external_version: Weka_3.7.10_9186, uploader: '1' }, { id: '66', full_name: weka.IBk(1), name: weka.IBk, version: '1', external_version: Weka_3.7.10_8034, uploader: '1' }, { id: '67', full_name: weka.BayesNet_K2(1), name: weka.BayesNet_K2, version: '1', external_version: Weka_3.7.10_8034, uploader: '1' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n500 - No results. There where no matches for the given constraints.\n501 - Illegal filter specified.\n502 - Filter values/ranges not properly specified.\n503 - Can not specify an offset without a limit.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /flow/tag: + post: + tags: + - flow + summary: 'Tag a flow' + description: 'Tags a flow.' + operationId: 'Api_flow::flow_tag' + parameters: + - + name: flow_id + in: query + description: 'Id of the flow.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the tagged flow' + content: + application/json: + schema: + properties: + flow_tag: { $ref: '#/components/schemas/inline_response_200_12_flow_tag' } + type: object + example: + flow_tag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /flow/untag: + post: + tags: + - flow + summary: 'Untag a flow' + description: 'Untags a flow.' + operationId: 'Api_flow::flow_untag' + parameters: + - + name: flow_id + in: query + description: 'Id of the flow.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the untagged flow' + content: + application/json: + schema: + properties: + flow_untag: { $ref: '#/components/schemas/inline_response_200_13_flow_untag' } + type: object + example: + flow_untag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged\nby another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/flow/exists/{name}/{version}': + get: + tags: + - flow + summary: 'Check whether flow exists' + description: 'Checks whether a flow with the given name and (external) version exists.' + operationId: 'Api_flow::flow_exists' + parameters: + - + name: name + in: path + description: 'The name of the flow.' + required: true + schema: + type: string + - + name: version + in: path + description: 'The external version of the flow' + required: true + schema: + type: string + responses: + '200': + description: 'A list of flows' + content: + application/json: + schema: + properties: + flow_exists: { $ref: '#/components/schemas/inline_response_200_10_flow_exists' } + type: object + example: + flow_exists: + exists: 'true' + id: '65' + '412': + description: 'Precondition failed. An error code and message are returned.\n330 - Mandatory fields not present. Please provide name and external_version.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/flow/{id}': + get: + tags: + - flow + summary: 'Get flow description' + description: 'Returns information about a flow. The information includes the name, information about the creator, dependencies, parameters, run instructions and more.' + operationId: 'Api_flow::flow' + parameters: + - + name: id + in: path + description: 'ID of the flow.' + required: true + schema: + type: integer + responses: + '200': + description: 'A flow description' + content: + application/json: + schema: + $ref: '#/components/schemas/Flow' + example: + flow: + id: '100' + uploader: '1' + name: weka.J48 + version: '2' + external_version: Weka_3.7.5_9117 + description: ... + upload_date: '2014-04-23 18:00:36' + language: Java + dependencies: Weka_3.7.5 + parameter: [{ name: A, data_type: flag, default_value: [], description: 'Laplace smoothing...' }, { name: C, data_type: option, default_value: '0.25', description: 'Set confidence threshold...' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n180 - Please provide flow id.\n181 - Unknown flow. The flow with the given ID was not found in the database.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + delete: + tags: + - flow + summary: 'Delete a flow' + description: 'Deletes a flow. Upon success, it returns the ID of the deleted flow.' + operationId: 'Api_flow::flow_delete' + parameters: + - + name: id + in: path + description: 'Id of the flow.' + required: true + schema: + type: integer + - + name: api_key + in: query + description: 'API key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'ID of the deleted flow' + content: + application/json: + schema: + properties: + flow_delete: { $ref: '#/components/schemas/inline_response_200_8_flow_delete' } + type: object + example: + flow_delete: + id: '4328' + '412': + description: 'Precondition failed. An error code and message are returned.\n320 - Please provide API key. In order to remove your content, please authenticate.\n321 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n322 - Flow does not exists. The flow ID could not be linked to an existing flow.\n323 - Flow is not owned by you. The flow is owned by another user. Hence you cannot delete it.\n324 - Flow is in use by other content. Can not be deleted. The flow is used in runs, evaluations or as a component of another flow. Delete other content before deleting this flow.\n325 - Deleting flow failed. Deleting the flow failed. Please contact\nsupport team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /flow: + post: + tags: + - flow + summary: 'Upload a flow' + description: 'Uploads a flow. Upon success, it returns the flow id.' + operationId: 'Api_flow::flow_upload' + parameters: + - + name: description + in: query + description: 'An XML file describing the flow. Only name and description are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.implementation.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/flow).' + required: true + schema: + type: file + - + name: flow + in: query + description: 'The actual flow, being a source (or binary) file.' + required: false + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the uploaded flow' + content: + application/json: + schema: + properties: + upload_flow: { $ref: '#/components/schemas/inline_response_200_9_upload_flow' } + type: object + example: + upload_flow: + id: '2520' + '412': + description: 'Precondition failed. An error code and message are returned.\n160 - Error in file uploading. There was a problem with the file upload.\n161 - Please provide description xml.\n163 - Problem validating uploaded description file. The XML description format does not meet the standards.\n164 - Flow already stored in database. Please change name or version number\n165 - Failed to insert flow. There can be many causes for this error. If you included the implements field, it should be an existing entry in the algorithm or math_function table. Otherwise it could be an internal server error. Please contact API support team.\n166 - Failed to add flow to database. Internal server error, please contact API administrators\n167 - Illegal files uploaded. An non required file was uploaded.\n168 - The provided md5 hash equals not the server generated md5 hash of the file.\n169 - Please provide API key. In order to share content, please authenticate and provide API key.\n170 - Authentication failed. The API key was not valid. Please try to login again, or contact API administrators\n171 - Flow already exists. This flow is already in the database\n172 - XSD not found. Please contact API support team\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /run/tag: + post: + tags: + - run + summary: 'Tag a run' + description: 'Tags a run.' + operationId: 'Api_run::run_tag' + parameters: + - + name: run_id + in: query + description: 'Id of the run.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the tagged run' + content: + application/json: + schema: + properties: + run_tag: { $ref: '#/components/schemas/inline_response_200_19_run_tag' } + type: object + example: + run_tag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /run/untag: + post: + tags: + - run + summary: 'Untag a run' + description: 'Untags a run.' + operationId: 'Api_run::run_untag' + parameters: + - + name: run_id + in: query + description: 'Id of the run.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the untagged run' + content: + application/json: + schema: + properties: + run_untag: { $ref: '#/components/schemas/inline_response_200_20_run_untag' } + type: object + example: + run_untag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/run/list/{filters}': + get: + tags: + - run + summary: 'List and filter runs' + description: 'List runs, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form ''/run/list/{filter}/{value}/{filter}/{value}/...'' Returns an array with all runs that match the constraints. A maximum of 10,000 results are returned, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain tasks, flows, setups, or uploaders.' + operationId: 'Api_run::run_list' + parameters: + - + name: filters + in: path + description: "Any combination of these filters\r\n /tag/{tag} - return only runs tagged with the given tag.\r\n /run/{ids} - return only specific runs, specified as a comma-separated list of run IDs, e.g. ''1,2,3''\r\n /task/{ids} - return only runs on specific tasks, specified as a comma-separated list of task IDs, e.g. ''1,2,3''\r\n /flow/{ids} - return only runs on specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3''\r\n /setup/{ids} - return only runs with specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3''\r\n /uploader/{ids} - return only runs uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n " + required: true + schema: + type: string + responses: + '200': + description: 'A list of runs descriptions' + content: + application/json: + schema: + $ref: '#/components/schemas/RunList' + example: + runs: + run: [{ upload_time: '2014-04-06 23:30:40', task_id: '28', run_id: '100', error_message: [], setup_id: '12', uploader: '1', flow_id: '67' }, { upload_time: '2014-04-06 23:30:40', task_id: '48', run_id: '101', error_message: [], setup_id: '6', uploader: '1', flow_id: '61' }, { upload_time: '2014-04-06 23:30:40', task_id: '41', run_id: '102', error_message: [], setup_id: '3', uploader: '1', flow_id: '58' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n510 - Please provide at least task, flow or setup, uploader or run, to filter results, or limit the number of responses. The number of runs is huge. Please limit the result space.\n511 - Input not safe. The input parameters (task_id, setup_id, flow_id, run_id, uploader_id) did not meet the constraints (comma separated list of integers).\n512 - There where no results. Check whether there are runs under the given constraint.\n513 - Too many results. Given the constraints, there were still too many results. Please add filters to narrow down the list.\n514 - Illegal filter specified.\n515 - Offset specified without limit.\n516 - Requested result limit too high.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/run/{id}': + get: + tags: + - run + summary: 'Get run description' + description: 'Returns information about a run. The information includes the name, information about the creator, dependencies, parameters, run instructions and more.' + operationId: 'Api_run::run' + parameters: + - + name: id + in: path + description: 'ID of the run.' + required: true + schema: + type: integer + responses: + '200': + description: 'A run description' + content: + application/json: + schema: + $ref: '#/components/schemas/Run' + example: + run: + run_id: '100' + uploader: '1' + uploader_name: 'Jan van Rijn' + task_id: '28' + task_type: 'Supervised Classification' + task_evaluation_measure: predictive_accuracy + flow_id: '67' + flow_name: weka.BayesNet_K2(1) + setup_string: 'weka.classifiers.bayes.BayesNet -- -D -Q weka.classifiers.bayes.net.search.local.K2 -- -P 1 -S BAYES -E weka.classifiers.bayes.net.estimate.SimpleEstimator -- -A 0.5' + parameter_setting: [{ name: D, value: 'true' }, { name: Q, value: weka.classifiers.bayes.net.search.local.K2 }, { name: P, value: '1' }, { name: S, value: BAYES }] + input_data: { dataset: { did: '28', name: optdigits, url: 'https:\\/\\/www.openml.org\\/data\\/download\\/28\\/dataset_28_optdigits.arff' } } + output_data: { file: [{ did: '48838', file_id: '261', name: description, url: 'https:\\/\\/www.openml.org\\/data\\/download\\/261\\/weka_generated_run935374685998857626.xml' }, { did: '48839', file_id: '262', name: predictions, url: 'https:\\/\\/www.openml.org\\/data\\/download\\/262\\/weka_generated_predictions576954524972002741.arff' }], evaluation: [{ name: area_under_roc_curve, flow_id: '4', value: '0.990288', array_data: '[0.99724,0.989212,0.992776,0.994279,0.980578,0.98649,0.99422,0.99727,0.994858,0.976143]' }, { name: confusion_matrix, flow_id: '10', array_data: '[[544,1,0,0,7,0,1,0,0,1],[0,511,21,1,0,1,3,1,5,28],[0,7,511,1,0,1,0,3,23,11],[0,2,2,519,0,3,0,12,16,18],[0,3,0,0,528,0,4,21,6,6],[0,1,0,7,5,488,2,0,4,51],[1,7,0,0,2,0,548,0,0,0],[0,2,0,1,9,1,0,545,4,4],[1,25,2,2,3,6,2,1,503,9],[0,7,0,20,16,5,0,19,9,486]]' }, { name: f_measure, flow_id: '12', value: '0.922723', array_data: '[0.989091,0.898857,0.935041,0.92431,0.927944,0.918156,0.980322,0.933219,0.895018,0.826531]' }, { name: kappa, flow_id: '13', value: '0.913601' }] } + '412': + description: 'Precondition failed. An error code and message are returned.\n220 - Please provide run ID. In order to view run details, please provide the run ID.\n221 - Run not found. The run ID was invalid, run does not exist (anymore).\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + delete: + tags: + - run + summary: 'Delete run' + description: 'Deletes a run. Upon success, it returns the ID of the deleted run.' + operationId: 'Api_run::run_delete' + parameters: + - + name: id + in: path + description: 'Id of the run.' + required: true + schema: + type: integer + - + name: api_key + in: query + description: 'API key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'ID of the deleted run' + content: + application/json: + schema: + properties: + data_delete: { $ref: '#/components/schemas/inline_response_200_17_data_delete' } + type: object + example: + run_delete: + id: '2520' + '412': + description: 'Precondition failed. An error code and message are returned.\n390 - Please provide API key. In order to remove your content, please authenticate.\n391 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators\n392 - Run does not exists. The run ID could not be linked to an existing run.\n393 - Run is not owned by you. The run was owned by another user. Hence you cannot delete it.\n394 - Deleting run failed. Deleting the run failed. Please contact support team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/run/reset/{id}': + get: + tags: + - run + summary: 'Resets a run.' + description: 'Removes all run evaluations. When a run is reset, the runs will automatically be evaluated as soon as they are picked up by the evaluation engine again.' + operationId: 'Api_run::run_reset' + parameters: + - + name: id + in: path + description: 'Run ID.' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the evaluated run' + content: + application/json: + schema: + properties: + run_reset: { $ref: '#/components/schemas/inline_response_200_21_upload_flow' } + type: object + example: + run_reset: + id: '2520' + '412': + description: 'Precondition failed. An error code and message are returned.\n412 - Run does not exist\n413 - Run is not owned by you\n394 - Resetting run failed\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /run: + post: + tags: + - run + summary: 'Upload run' + description: 'Uploads a run. Upon success, it returns the run id.' + operationId: 'Api_run::run_upload' + parameters: + - + name: description + in: query + description: 'An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/run).' + required: true + schema: + type: file + - + name: predictions + in: query + description: 'The predictions generated by the run' + required: true + schema: + type: file + - + name: model_readable + in: query + description: 'The human-readable model generated by the run' + required: false + schema: + type: file + - + name: model_serialized + in: query + description: 'The serialized model generated by the run' + required: false + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the uploaded run' + content: + application/json: + schema: + properties: + upload_flow: { $ref: '#/components/schemas/inline_response_200_18_upload_flow' } + type: object + example: + upload_run: + id: '2520' + '412': + description: 'Precondition failed. An error code and message are returned.\n201 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n202 - Please provide run XML.\n203 - Could not validate run xml by XSD. Please double check that the xml is valid.\n204 - Unknown task. The task with the given ID was not found in the database.\n205 - Unknown flow. The flow with the given ID was not found in the database.\n206 - Invalid number of files. The number of uploaded files did not match the number of files expected for the task type\n207 - File upload failed. One of the files uploaded has a problem.\n208 - Error inserting setup record. Please contact api administrators\n210 - Unable to store run. Please contact api administrators.\n211 - Dataset not in database. One of the datasets of the task was not included in database, please contact api administrators.\n212 - Unable to store file. Please contact api administrators.\n213 - Parameter in run xml unknown. One of the parameters provided in the run xml is not registered as parameter for the flow nor its components.\n214 - Unable to store input setting. Please contact API support team.\n215 - Unable to evaluate predictions. Please contact API support team.\n216 - Error thrown by Java Application. Additional information field is provided.\n217 - Error processing output data. Unknown or inconsistent evaluation measure. One of the provided evaluation measures could not be matched with a record in the math_function or flow table.\n218 - Wrong flow associated with run. The flow implements a math_function, which is unable to generate predictions. Please select another flow.\n219 - Error reading the XML document. The XML description file could not be verified.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/run/trace/{id}': + get: + tags: + - run + summary: 'Get run trace' + description: 'Returns the optimization trace of run. The trace contains every setup tried, its evaluation, and whether it was selected.' + operationId: 'Api_run::run_trace' + parameters: + - + name: id + in: path + description: 'ID of the run.' + required: true + schema: + type: integer + responses: + '200': + description: 'A run trace description' + content: + application/json: + schema: + $ref: '#/components/schemas/RunTrace' + example: + trace: + run_id: '573055' + trace_iteration: { repeat: '0', fold: '0', iteration: '1', setup_string: { parameter_minNumObj: '1', parameter_confidenceFactor: '0.25' }, evaluation: '94.074074', selected: 'true' } + '412': + description: 'Precondition failed. An error code and message are returned.\n570 - No successful trace associated with this run\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + post: + tags: + - run + summary: 'Upload run trace' + description: 'Uploads a run trace. Upon success, it returns the run id.' + operationId: 'Api_run::run_trace_upload' + parameters: + - + name: id + in: path + description: 'ID of the run.' + required: true + schema: + type: integer + - + name: description + in: query + description: 'An XML file describing the trace. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.trace) and an [XML example](https://www.openml.org/api/v1/xml_example/run.trace).' + required: true + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the run with the trace' + content: + application/json: + schema: + properties: + upload_flow: { $ref: '#/components/schemas/inline_response_200_23_upload_flow' } + type: object + example: + run_trace: + id: '2520' + '412': + description: 'Precondition failed. An error code and message are returned.\n561 - Problem with uploaded trace file.\n562 - Problem validating xml trace file.\n563 - Problem loading xml trace file.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /run/evaluate: + post: + tags: + - run + summary: 'Uploads a run evaluation' + description: 'Uploads a run evaluation. When successful, it returns the run id.' + operationId: 'Api_run::run_evaluate' + parameters: + - + name: description + in: query + description: 'An XML file describing the run evaluation.Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.evaluate) and an [XML example](https://www.openml.org/api/v1/xml_example/run.evaluate).' + required: true + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the evaluated run' + content: + application/json: + schema: + properties: + upload_flow: { $ref: '#/components/schemas/inline_response_200_21_upload_flow' } + type: object + example: + run_evaluate: + id: '2520' + '412': + description: 'Precondition failed. An error code and message are returned.\n422 - Upload problem description XML\n423 - Problem validating uploaded description file\n424 - Problem opening description xml\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /setup/tag: + post: + tags: + - setup + summary: 'Tag a setup' + description: 'Tags a setup.' + operationId: 'Api_setup::setup_tag' + parameters: + - + name: setup_id + in: query + description: 'Id of the setup.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the tagged setup' + content: + application/json: + schema: + properties: + flow_tag: { $ref: '#/components/schemas/inline_response_200_15_flow_tag' } + type: object + example: + setup_tag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /setup/untag: + post: + tags: + - setup + summary: 'Untag a setup' + description: 'Untags a setup.' + operationId: 'Api_setup::setup_untag' + parameters: + - + name: setup_id + in: query + description: 'Id of the setup.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the untagged setup' + content: + application/json: + schema: + properties: + flow_untag: { $ref: '#/components/schemas/inline_response_200_16_flow_untag' } + type: object + example: + setup_untag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged\nby another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/setup/{id}': + get: + tags: + - setup + summary: 'Get a hyperparameter setup' + description: 'Returns information about a setup. The information includes the list of hyperparameters, with name, value, and default value.' + operationId: 'Api_setup::setup' + parameters: + - + name: id + in: path + description: 'ID of the hyperparameter setup (configuration). These IDs are stated in run descriptions.' + required: true + schema: + type: integer + responses: + '200': + description: 'A setup description' + content: + application/json: + schema: + $ref: '#/components/schemas/Setup' + example: + setup_parameters: + flow_id: '59' + parameter: [{ full_name: weka.JRip(1)_F, parameter_name: F, data_type: option, default_value: '3', value: '3' }, { full_name: weka.JRip(1)_N, parameter_name: 'N', data_type: option, default_value: '2.0', value: '2.0' }, { full_name: weka.JRip(1)_O, parameter_name: O, data_type: option, default_value: '2', value: '2' }, { full_name: weka.JRip(1)_S, parameter_name: S, data_type: option, default_value: '1', value: '1' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n280 - Please provide setup ID. In order to view setup details, please provide the run ID\n281 - Setup not found. The setup ID was invalid, or setup does not exist (anymore).\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + delete: + tags: + - setup + summary: 'Delete setup' + description: 'Deletes a setup. Upon success, it returns the ID of the deleted setup.' + operationId: 'Api_setup::setup_delete' + parameters: + - + name: id + in: path + description: 'Id of the setup.' + required: true + schema: + type: integer + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'ID of the deleted setup' + content: + application/json: + schema: + properties: + study_delete: { $ref: '#/components/schemas/inline_response_200_14_study_delete' } + type: object + example: + setup_delete: + id: '1' + '412': + description: 'Precondition failed. An error code and message are returned.\n401 - Authentication failed. Please provide API key. In order to remove your content, please authenticate.\n402 - Setup does not exists. The setup ID could not be linked to an existing setup.\n404 - Setup deletion failed. Setup is in use by other content (runs, schedules, etc). Can not be deleted.\n405 - Setup deletion failed. Please try again later.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/setup/list/{filters}': + get: + tags: + - setup + summary: 'List and filter setups' + description: 'List setups, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form ''/setup/list/{filter}/{value}/{filter}/{value}/...'' Returns an array with all evaluations that match the constraints. A maximum of 1,000 results are returned at a time, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain flows, setups, or tags.' + operationId: 'Api_setup::setup_list' + parameters: + - + name: filters + in: path + description: "Any combination of these filters\r\n /tag/{tag} - returns only setups tagged with the given tag.\r\n /flow/{ids} - return only setups for specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3''\r\n /setup/{ids} - return only specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n " + required: true + schema: + type: string + responses: + '200': + description: 'A list of setup descriptions' + content: + application/json: + schema: + $ref: '#/components/schemas/SetupList' + example: + setups: + setup: [{ setup_id: '10', flow_id: '65', parameter: [{ id: '4144', flow_id: '65', flow_name: weka.RandomForest, full_name: weka.RandomForest(1)_I, parameter_name: I, data_type: option, default_value: '10', value: '10' }, { id: '4145', flow_id: '65', flow_name: weka.RandomForest, full_name: weka.RandomForest(1)_K, parameter_name: K, data_type: option, default_value: '0', value: '0' }] }] + '412': + description: 'Precondition failed. An error code and message are returned.\n670 - Please specify at least one filter.\n671 - Illegal filter.\n672 - Illegal filter input.\n673 - Result set too big. Please use one of the filters or the limit option.\n674 - No results, please check the filter.\n675 - Cannot specify offset without limit.\n676 - Requested result limit too high.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /study: + post: + tags: + - study + summary: 'Create new study' + description: 'Creates a new study. Upon success, it returns the study id.' + operationId: 'Api_study::study_create' + parameters: + - + name: description + in: query + description: 'An XML file describing the study. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.study.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/study).' + required: true + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the uploaded study' + content: + application/json: + schema: + properties: + upload_study: { $ref: '#/components/schemas/inline_response_200_25_upload_study' } + type: object + example: + upload_study: + id: '4328' + '412': + description: 'Precondition failed. An error code and message are returned.\n1031 - Description file not present. Please upload the study description.\n1032 - Problem validating uploaded description file. The XML description format does not meet the standards. See the XSD schema.\n1033 - Illegal main entity type. Currently only collections of tasks and can be created.\n1034 - Linked entities are not of the correct type fot this study.\n1035 - Benchmark suites can only be linked to run studies.\n1036 - Referred benchmark suite cannot be found.\n1037 - Referred benchmark suite should be a task collection.\n1038 - Study alias is not unique.\n1039 - Dataset insertion problem. Please contact the administrators.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/study/{id}/attach': + post: + tags: + - study + summary: 'Attach a new entity to a study' + description: 'Attach a new entity to an exising study. Upon success, it returns the study id, type, and linked entities.' + operationId: 'Api_study::study_attach' + parameters: + - + name: id + in: path + description: 'Id of the study. Supplied in the URL path.' + required: true + schema: + type: integer + - + name: ids + in: query + description: 'Comma-separated list of entity IDs to be attached to the study. For instance, if this is a run study, the list of run IDs that need to be added (attached) to the study. Must be supplied as a POST variable.' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Properties of the updated study' + content: + application/json: + schema: + properties: + study_attach: { $ref: '#/components/schemas/inline_response_200_26_study_attach' } + type: object + example: + study_attach: + id: '1' + main_entity_type: task + linked_entities: '5' + '412': + description: 'Precondition failed. An error code and message are returned.\n1041 - Could not find study. Check the study ID in your request.\n1042 - Cannnot attach entities to legacy studies.\n1043 - Please provide POST field ''ids''.\n1044 - Please ensure that the ''ids'' in the POST field is a list of natural numbers.\n1045 - Could not attach entities to the study. It appears as if the entity does not exist.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/study/{id}/detach': + post: + tags: + - study + summary: 'Detach an entity from a study' + description: 'Detach an entity from an exising study. Upon success, it returns the study id, type, and linked entities.' + operationId: 'Api_study::study_detach' + parameters: + - + name: id + in: path + description: 'Id of the study.' + required: true + schema: + type: integer + - + name: ids + in: query + description: 'Comma-separated list of entity IDs to be detached from the study. For instance, if this is a run study, the list of run IDs that need to be removed (detached) from the study. Must be supplied as a POST variable.' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Properties of the updated study' + content: + application/json: + schema: + properties: + upload_study: { $ref: '#/components/schemas/inline_response_200_26_study_attach' } + type: object + example: + study_detach: + id: '1' + main_entity_type: task + linked_entities: '5' + '412': + description: 'Precondition failed. An error code and message are returned.\n1041 - Could not find study. Check the study ID in your request.\n1042 - Cannot attach entities to legacy studies.\n1043 - Please provide POST field ''ids''.\n1044 - Please ensure that the ''ids'' in the POST field is a list of natural numbers.\n1046 - Could not detach entities from the study. It appears as if the entity does not exist. \n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/study/{id}': + get: + tags: + - study + summary: 'Get study description by study id or alias' + description: 'Returns information about the study with the given id or alias.' + operationId: 'Api_study::study_get' + parameters: + - + name: id + in: path + description: 'ID or alias of the study.' + required: true + schema: + type: string + responses: + '200': + description: 'A study description' + content: + application/json: + schema: + $ref: '#/components/schemas/Study' + example: + study: + id: '99' + main_entity_type: task + name: 'CC18 benchmark suite' + description: 'CC18 benchmark suite' + creation_date: '2019-02-16T17:35:58' + creator: '1159' + data: { data_id: ['1', '2', '3'] } + tasks: { task_id: ['1', '2', '3'] } + '412': + description: 'Precondition failed. An error code and message are returned.\n601 - Unknown study. The study with the given id or alias was not found in the database\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + delete: + tags: + - study + summary: 'Delete study' + description: 'Deletes a study. Upon success, it returns the ID of the deleted study.' + operationId: 'Api_study::study_delete' + parameters: + - + name: id + in: path + description: 'Id of the study.' + required: true + schema: + type: integer + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'ID of the deleted study' + content: + application/json: + schema: + properties: + study_delete: { $ref: '#/components/schemas/inline_response_200_24_study_delete' } + type: object + example: + study_delete: + id: '1' + '412': + description: 'Precondition failed. An error code and message are returned.\n591 - Please provide API key. In order to remove your content, please authenticate.\n592 - Study does not exists. The study ID could not be linked to an existing study.\n593 - Study deletion failed. Please try again later.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/study/list/{filters}': + get: + tags: + - study + summary: 'List all studies (collections of items)' + description: 'List studies, optionally filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form ''/study/list/{filter}/{value}/{filter}/{value}/...'' Returns an array with all studies that match the constraints.' + operationId: 'Api_study::study_list' + parameters: + - + name: filters + in: path + description: "Any combination of these filters\r\n /main_entity_type/{type} - only return studies collecting entities of a given type (e.g. 'task' or 'run').\r\n /uploader/{ids} - return only evaluations uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3''\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified.\r\n " + required: true + schema: + type: string + responses: + '200': + description: 'A list of studies' + content: + application/json: + schema: + $ref: '#/components/schemas/StudyList' + example: + study_list: + study: [{ id: '1', alias: Study_1, name: 'A large-scale comparison of classification algorithms', creation_date: '2017-07-20 15:51:20', creator: '2' }, { id: '2', alias: Study_2, name: 'Fast Algorithm Selection using Learning Curves', creation_date: '2017-07-20 15:51:20', creator: '2' }] + '412': + description: 'Precondition failed. An error code and message are returned.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /task/tag: + post: + tags: + - task + summary: 'Tag a task' + description: 'Tags a task.' + operationId: 'Api_task::task_tag' + parameters: + - + name: task_id + in: query + description: 'Id of the task.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'The id of the tagged task' + content: + application/json: + schema: + properties: + task_tag: { $ref: '#/components/schemas/inline_response_200_6_task_tag' } + type: object + example: + task_tag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, task_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, task_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, task, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /task/untag: + post: + tags: + - task + summary: 'Untag a task' + description: 'Untags a task.' + operationId: 'Api_task::task_untag' + parameters: + - + name: task_id + in: query + description: 'Id of the task.' + required: true + schema: + type: integer + - + name: tag + in: query + description: 'Tag name' + required: true + schema: + type: string + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'A the features of the task' + content: + application/json: + schema: + properties: + task_untag: { $ref: '#/components/schemas/inline_response_200_7_task_untag' } + type: object + example: + task_untag: + id: '2' + '412': + description: 'Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, task_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, task, flow, run} not found. The provided entity_id {data_id, task_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, task, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/task/list/{filters}': + get: + tags: + - task + summary: 'List and filter tasks' + description: 'List tasks, possibly filtered by a range of properties from the task itself or from the underlying dataset. Any number of properties can be combined by listing them one after the other in the form ''/task/list/{filter}/{value}/{filter}/{value}/...'' Returns an array with all tasks that match the constraints.' + operationId: 'Api_task::task_list' + parameters: + - + name: filters + in: path + description: "Any combination of these filters\r\n /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, tasks 11..15 will be returned. Both limit and offset need to be specified.\r\n /status/{status} - returns only tasks with a given status, either 'active', 'deactivated', or 'in_preparation'.\r\n /type/{type_id} - returns only tasks with a given task type id. See the list of task types of the ID's (e.g. 1 = Supervised Classification).\r\n /tag/{tag} - returns only tasks tagged with the given tag.\r\n /data_tag/{tag} - returns only tasks for which the underlying dataset is tagged with the given tag.\r\n /{data_quality}/{range} - returns only tasks for which the underlying datasets have certain qualities. {data_quality} can be data_id, data_name, number_instances, number_features, number_classes, number_missing_values. {range} can be a specific value or a range in the form 'low..high'. Multiple qualities can be combined, as in 'number_instances/0..50/number_features/0..10'.\r\n " + required: true + schema: + type: string + responses: + '200': + description: 'A list of tasks with the given tag' + content: + application/json: + schema: + $ref: '#/components/schemas/TaskList' + example: + task: + task: [{ task_id: '1', task_type: 'Supervised Classification', did: '1', name: anneal, status: active, format: ARFF, input: [{ name: estimation_procedure, value: '1' }, { name: evaluation_measures, value: predictive_accuracy }, { name: source_data, value: '1' }, { name: target_feature, value: class }], quality: [{ name: MajorityClassSize, value: '684' }, { name: MaxNominalAttDistinctValues, value: '10.0' }, { name: MinorityClassSize, value: '0' }, { name: NumBinaryAtts, value: '14.0' }, { name: NumberOfClasses, value: '6' }, { name: NumberOfFeatures, value: '39' }, { name: NumberOfInstances, value: '898' }, { name: NumberOfInstancesWithMissingValues, value: '0' }, { name: NumberOfMissingValues, value: '0' }, { name: NumberOfNumericFeatures, value: '6' }, { name: NumberOfSymbolicFeatures, value: '32' }], tag: [basic, study_1, study_7, under100k, under1m] }] + '412': + description: 'Precondition failed. An error code and message are returned.\n480 - Illegal filter specified.\n481 - Filter values/ranges not properly specified.\n482 - No results. There where no matches for the given constraints.\n483 - Can not specify an offset without a limit.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '/task/{id}': + get: + tags: + - task + summary: 'Get task description' + description: 'Returns information about a task. The information includes the task type, input data, train/test sets, and more.' + operationId: 'Api_task::task' + parameters: + - + name: id + in: path + description: 'ID of the task.' + required: true + schema: + type: integer + responses: + '200': + description: 'A task description' + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + example: + task: + task_id: '1' + task_type: 'Supervised Classification' + input: [{ name: source_data, data_set: { data_set_id: '1', target_feature: class } }, { name: estimation_procedure, estimation_procedure: { type: crossvalidation, data_splits_url: 'https://www.openml.org/api_splits/get/1/Task_1_splits.arff', parameter: [{ name: number_repeats, value: '1' }, { name: number_folds, value: '10' }, { name: percentage }, { name: stratified_sampling, value: 'true' }] } }, { name: cost_matrix, cost_matrix: [] }, { name: evaluation_measures, evaluation_measures: { evaluation_measure: predictive_accuracy } }] + output: { name: predictions, predictions: { format: ARFF, feature: [{ name: repeat, type: integer }, { name: fold, type: integer }, { name: row_id, type: integer }, { name: confidence.classname, type: numeric }, { name: prediction, type: string }] } } + tag: [basic, study_1, under100k, under1m] + '412': + description: 'Precondition failed. An error code and message are returned.\n150 - Please provide task_id.\n151 - Unknown task. The task with the given id was not found in the database\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + delete: + tags: + - task + summary: 'Delete task' + description: 'Deletes a task. Upon success, it returns the ID of the deleted task.' + operationId: 'Api_task::task_delete' + parameters: + - + name: id + in: path + description: 'Id of the task.' + required: true + schema: + type: integer + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'ID of the deleted task' + content: + application/json: + schema: + properties: + task_delete: { $ref: '#/components/schemas/inline_response_200_4_task_delete' } + type: object + example: + task_delete: + id: '4328' + '412': + description: 'Precondition failed. An error code and message are returned.\n450 - Please provide API key. In order to remove your content, please authenticate.\n451 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n452 - Task does not exists. The task ID could not be linked to an existing task.\n454 - Task is executed in some runs. Delete these first.\n455 - Deleting the task failed. Please contact support team.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /task: + post: + tags: + - task + summary: 'Upload task' + description: 'Uploads a task. Upon success, it returns the task id.' + operationId: 'Api_task::task_upload' + parameters: + - + name: description + in: query + description: 'An XML file describing the task. Only name, description, and task format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.task.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/task).' + required: true + schema: + type: file + - + name: api_key + in: query + description: 'Api key to authenticate the user' + required: true + schema: + type: string + responses: + '200': + description: 'Id of the uploaded task' + content: + application/json: + schema: + properties: + upload_task: { $ref: '#/components/schemas/inline_response_200_5_upload_task' } + type: object + example: + upload_task: + id: '4328' + '412': + description: 'Precondition failed. An error code and message are returned.\n530 - Description file not present. Please upload the task description.\n531 - Internal error. Please contact api support team\n532 - Problem validating uploaded description file. The XML description format does not meet the standards\n533 - Task already exists.\n534 - Error creating the task.\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /tasktype/list: + get: + tags: + - tasktype + summary: 'List all task types' + description: 'Returns an array with all task types in the system.' + responses: + default: + description: 'Unexpected error' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + '200': + description: 'A task description' + content: + application/json: + schema: + $ref: '#/components/schemas/TaskTypeList' + example: + task_types: + task_type: [{ id: '1', name: 'Supervised Classification', description: 'In supervised classification, you are given ...', creator: 'Joaquin Vanschoren, Jan van Rijn, Luis Torgo, Bernd Bischl' }, { id: '2', name: 'Supervised Regression', description: 'Given a dataset with a numeric target ...', creator: 'Joaquin Vanschoren, Jan van Rijn, Luis Torgo, Bernd Bischl' }] + '/tasktype/{id}': + get: + tags: + - tasktype + summary: 'Get task type description' + description: 'Returns information about a task type. The information includes a description, the given inputs and the expected outputs.' + parameters: + - + name: id + in: path + description: 'ID of the task.' + required: true + schema: + type: integer + responses: + '200': + description: 'A task type description' + content: + application/json: + schema: + $ref: '#/components/schemas/TaskType' + example: + task_type: + id: '1' + name: 'Supervised Classification' + description: "In supervised classification, you are given an input dataset in which instances are labeled with a certain class. The goal is to build a model that predicts the class for future unlabeled instances. The model is evaluated using a train-test procedure, e.g. cross-validation.

\\\r\n * \\\r\n * To make results by different users comparable, you are given the exact train-test folds to be used, and you need to return at least the predictions generated by your model for each of the test instances. OpenML will use these predictions to calculate a range of evaluation measures on the server.

\\\r\n * \\\r\n * You can also upload your own evaluation measures, provided that the code for doing so is available from the implementation used. For extremely large datasets, it may be infeasible to upload all predictions. In those cases, you need to compute and provide the evaluations yourself.

\\\r\n * \\\r\n * Optionally, you can upload the model trained on all the input data. There is no restriction on the file format, but please use a well-known format or PMML." + creator: ['Joaquin Vanschoren', 'Jan van Rijn', 'Luis Torgo', 'Bernd Bischl'] + contributor: ['Bo Gao', 'Simon Fischer', 'Venkatesh Umaashankar', 'Michael Berthold', 'Bernd Wiswedel', 'Patrick Winter'] + creation_date: '2013-01-24 00:00:00' + input: [{ name: source_data, requirement: required, data_type: numeric }, { name: target_feature, requirement: required, data_type: string }, { name: estimation_procedure, requirement: required, data_type: numeric }, { name: cost_matrix, data_type: json }, { name: custom_testset, data_type: json }, { name: evaluation_measures, data_type: string }] + '412': + description: 'Precondition failed. An error code and message are returned.\n240 - Please provide task type ID.\n241 - Unknown task type. The task type with the given id was not found in the database\n' + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + /user/list: + get: + tags: + - user + summary: 'List all users by user id' + description: 'Returns an array with all user ids and names.' + operationId: 'Api_user::username_list' + responses: + '200': + description: 'A list of users' + content: + application/json: + schema: + $ref: '#/components/schemas/UserList' + example: + users: + user: [{ id: '1', username: janvanrijn@gmail.com }, { id: '2', username: joaquin.vanschoren@gmail.com }] +components: + schemas: + inline_response_200_16_flow_untag: + properties: + id: + description: 'ID of the untagged setup' + type: string + type: object + EvaluationMeasureList_evaluation_measures_measures: + properties: + measure: + description: 'The evaluation measure names' + type: array + items: + type: string + type: object + inline_response_200_10_flow_exists: + properties: + id: + description: 'The id of the flow with the given name and (external) version' + type: string + exists: + description: 'true or false' + type: string + type: object + Data_data_set_description: + properties: + default_target_attribute: + description: 'For tabular data, the name of the column that is typically used as the target attribute for that data set' + type: string + upload_date: + description: 'The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss' + type: string + version_label: + description: 'The version of the dataset, as defined by the uploader, for reference. Can be any format as long as it is unique.' + type: string + description: + description: 'Wiki description of the dataset, in (Git flavoured) markdown format' + type: string + format: + description: 'Data format, for instance ARFF' + type: string + url: + description: 'The URL where the data can be downloaded' + type: string + tag: + description: 'Tags added by OpenML users. Includes study tags in the form `study_1`' + type: array + items: + type: string + visibility: + description: 'Who can see the dataset. For instance `public`.' + type: string + md5_checksum: + description: 'Checksum to verify downloads of the dataset' + type: string + version: + description: 'The version of the dataset, set by OpenML. A positive integer' + type: string + status: + description: 'active, in_preparation, or deactivated' + type: string + file_id: + description: 'The ID of the dataset file stored on the OpenML server' + type: string + licence: + description: 'The licence granted for using the dataset, for instance Public or CC-BY' + type: string + original_data_url: + description: 'The URL where the original data is hosted.' + type: string + id: + description: 'ID of the dataset, a positive integer' + type: string + name: + description: 'The name of the dataset' + type: string + type: object + DataList_data_dataset: + properties: + did: + description: 'The dataset ID' + type: string + status: + description: 'The dataset status, either in_preparation, active, or deactivated' + type: string + quality: + type: array + items: + $ref: '#/components/schemas/DataList_data_quality' + name: + description: 'The dataset name' + type: string + format: + description: 'The data format of the dataset, e.g. ARFF' + type: string + type: object + Task_task_description_estimation_procedure: + properties: + parameter: + type: array + items: + $ref: '#/components/schemas/Task_task_description_estimation_procedure_parameter' + type: + description: 'The type of procedure, e.g. crossvalidation' + type: string + data_splits_url: + description: 'The url where the data splits can be downloaded' + type: string + type: object + DataList_data_quality: + properties: + name: + description: 'The name of the property' + type: string + value: + description: 'The value of the property' + type: string + type: object + FlowList_flows_flow: + properties: + full_name: + description: 'The full flow name (name + internal version number)' + type: string + external_version: + description: 'The external flow version' + type: string + version: + description: 'The internal flow version' + type: string + uploader: + description: 'The ID of the person who uploaded the flow' + type: string + id: + description: 'The flow ID' + type: string + name: + description: 'The flow name' + type: string + type: object + Run_run_description_input_data_dataset: + properties: + did: + description: 'The id of the dataset' + type: string + url: + description: 'The download url of the dataset' + type: string + name: + description: 'The name of the dataset' + type: string + type: object + EvaluationList_evaluations: + properties: + evaluation: + type: array + items: + $ref: '#/components/schemas/EvaluationList_evaluations_evaluation' + type: object + inline_response_200_14_study_delete: + properties: + id: + description: 'ID of the deleted setup, a positive integer' + type: string + type: object + DataUnprocessed: + properties: + data_unprocessed: + $ref: '#/components/schemas/DataUnprocessed_data_unprocessed' + type: object + DataUnprocessed_data_unprocessed_dataset: + properties: + did: + description: 'ID of the dataset a positive integer' + type: string + status: + description: 'Status of the dataset' + type: string + version: + description: 'Version of the dataset, a positive integer' + type: string + name: + description: 'The name of the dataset' + type: string + format: + description: 'The dataset format, e.g. ARFF' + type: string + type: object + EstimationProcedureList_estimationprocedures: + properties: + estimationprocedure: + type: array + items: + $ref: '#/components/schemas/EstimationProcedureList_estimationprocedures_estimationprocedure' + type: object + TaskTypeList: + properties: + task_types: + $ref: '#/components/schemas/TaskTypeList_task_types' + type: object + Run_run_description_output_data_evaluation: + properties: + array_data: + description: 'For composite evaluation measures (e.g. per-class measures, confusion matrix), a string (JSON) representation of the evaluation.' + type: string + name: + description: 'The name of the evaluation measure' + type: string + value: + description: 'The result of the evaluation' + type: string + flow_id: + description: 'The id of the code used to compute this evaluation method' + type: string + type: object + TaskList_task_quality: + properties: + name: + description: 'The name of the quality' + type: string + value: + description: 'The value of the quality' + type: string + type: object + Task_task_description: + properties: + input: + type: array + items: + $ref: '#/components/schemas/Task_task_description_input' + task_type: + description: 'The type of the task, e.g. Supervised Classification' + type: string + tag: + description: 'Tags added by OpenML uers. Includes study tags in the form ''study_1''' + type: array + items: + type: string + task_id: + description: 'ID of the task, a positive integer' + type: string + output: + type: array + items: + $ref: '#/components/schemas/Task_task_description_output' + type: object + inline_response_200_9_upload_flow: + properties: + id: + description: 'ID of the uploaded flow, a positive integer' + type: string + type: object + Flow_flow_description: + properties: + upload_date: + description: 'The datetime that the flow was uploaded, format yyyy-MM-dd HH:mm:ss' + type: string + description: + description: 'Wiki description of the flow, in (Git flavoured) markdown format' + type: string + language: + description: 'The programming language the flow is written in.' + type: string + parameter: + type: array + items: + $ref: '#/components/schemas/Flow_flow_description_parameter' + tag: + description: 'Tags added by OpenML users. Includes study tags in the form `study_1`' + type: array + items: + type: string + version: + description: 'The version of the flow, set by OpenML. A positive integer' + type: string + version_label: + description: 'The version of the flow, as defined by the uploader, for reference. Can be any format as long as it is unique.' + type: string + dependencies: + description: 'The libraries that this flow depends on, and their version numbers.' + type: string + uploader: + description: 'The uploader of the flow' + type: string + id: + description: 'ID of the flow, a positive integer' + type: string + name: + description: 'The name of the flow' + type: string + type: object + Task: + properties: + task_description: + $ref: '#/components/schemas/Task_task_description' + type: object + Setup: + properties: + setup_parameters: + $ref: '#/components/schemas/Setup_setup_parameters' + type: object + FlowList_flows: + properties: + flow: + type: array + items: + $ref: '#/components/schemas/FlowList_flows_flow' + type: object + RunTrace: + properties: + trace: + $ref: '#/components/schemas/RunTrace_trace' + type: object + Task_task_description_predictions_feature: + properties: + type: + description: 'The type of the prediction feature, e.g. integer' + type: string + name: + description: 'The name of the prediction feature, e.g. row_id' + type: string + type: object + inline_response_200_24_study_delete: + properties: + id: + description: 'ID of the deleted study, a positive integer' + type: string + type: object + inline_response_200_5_upload_task: + properties: + id: + description: 'ID of the uploaded task, a positive integer' + type: string + type: object + inline_response_200_13_flow_untag: + properties: + id: + description: 'ID of the untagged flow' + type: string + type: object + UserList_users: + properties: + user: + type: array + items: + $ref: '#/components/schemas/UserList_users_user' + type: object + DataFeatures: + properties: + data_features: + $ref: '#/components/schemas/DataFeatures_data_features' + type: object + Task_task_description_predictions: + properties: + feature: + type: array + items: + $ref: '#/components/schemas/Task_task_description_predictions_feature' + format: + description: 'The fromat of the predictions, e.g. ARFF' + type: string + type: object + inline_response_200_15_flow_tag: + properties: + id: + description: 'ID of the tagged setup' + type: string + type: object + Setup_setup_parameters: + properties: + parameter_setting: + type: array + items: + $ref: '#/components/schemas/Setup_setup_parameters_parameter_setting' + flow_id: + description: 'ID of the flow, a positive integer' + type: string + type: object + DataList: + properties: + data: + $ref: '#/components/schemas/DataList_data' + type: object + inline_response_200_26_study_attach: + properties: + linked_entities: + description: 'The number of linked entities' + type: string + main_entity_type: + description: 'Main entity type of the of the study' + type: string + id: + description: 'ID of the study, a positive integer' + type: string + type: object + inline_response_200_2_data_tag: + properties: + id: + description: 'ID of the tagged dataset' + type: string + type: object + inline_response_200_23_upload_flow: + properties: + id: + description: 'ID of the run with the trace, a positive integer' + type: string + type: object + EvaluationRequest_evaluation_request: + properties: + run: + $ref: '#/components/schemas/EvaluationRequest_evaluation_request_run' + type: object + Run: + properties: + run_description: + $ref: '#/components/schemas/Run_run_description' + type: object + inline_response_200_6_task_tag: + properties: + id: + description: 'ID of the tagged task' + type: string + type: object + RunList: + properties: + runs: + $ref: '#/components/schemas/RunList_runs' + type: object + inline_response_200_17_data_delete: + properties: + id: + description: 'ID of the deleted run, a positive integer' + type: string + type: object + Task_task_description_input: + properties: + data_set: + $ref: '#/components/schemas/Task_task_description_data_set' + cost_matrix: + description: 'The cost matrix, indicating the costs for each type of misclassification' + type: array + items: + type: array + items: + type: integer + format: int64 + name: + description: 'The name of the input, e.g. source_data' + type: string + evaluation_measures: + $ref: '#/components/schemas/Task_task_description_evaluation_measures' + estimation_procedure: + $ref: '#/components/schemas/Task_task_description_estimation_procedure' + type: object + UserList: + properties: + users: + $ref: '#/components/schemas/UserList_users' + type: object + Study_study_runs: + properties: + run_id: + type: array + items: + type: string + type: object + DataFeatures_data_features_feature: + properties: + index: + description: 'Feature index' + type: string + name: + description: 'Feature name' + type: string + data_type: + description: 'Feature data type' + type: string + is_target: + description: 'Whether this feature is seen as a target feature' + type: string + is_ignore: + description: 'Whether this feature should be ignored in modelling (e.g. every value is unique)' + type: string + is_row_identifier: + description: 'Whether this feature is a row identifier' + type: string + type: object + inline_response_200_21_upload_flow: + properties: + id: + description: 'ID of the evaluated run, a positive integer' + type: string + type: object + TaskType: + properties: + description: + description: 'A description of the task type' + type: string + date: + description: 'The date when the task type was created' + type: string + output: + type: array + items: + $ref: '#/components/schemas/TaskType_output' + contributor: + type: array + items: + type: string + input: + type: array + items: + $ref: '#/components/schemas/TaskType_input' + id: + description: 'ID of the task type, a positive integer' + type: string + name: + description: 'The name of the task type, e.g. Supervised Classification' + type: string + type: object + Run_run_description_output_data_file: + properties: + did: + description: 'The id of the uploaded file' + type: string + file_id: + description: 'The reference id of the uploaded file, for downloading afterward' + type: string + name: + description: 'The name of the uploaded file (e.g., description, predictions, model,...)' + type: string + type: object + TaskType_input: + properties: + data_set: + $ref: '#/components/schemas/Task_task_description_data_set' + cost_matrix: + type: array + items: + type: array + items: + type: integer + format: int64 + name: + description: 'The name of the input, e.g. source_data' + type: string + evaluation_measures: + $ref: '#/components/schemas/Task_task_description_evaluation_measures' + estimation_procedure: + $ref: '#/components/schemas/Task_task_description_estimation_procedure' + type: object + Run_run_description_output_data: + properties: + evaluation: + type: array + items: + $ref: '#/components/schemas/Run_run_description_output_data_evaluation' + file: + type: array + items: + $ref: '#/components/schemas/Run_run_description_output_data_file' + type: object + inline_response_200_3_data_untag: + properties: + id: + description: 'ID of the untagged dataset' + type: string + type: object + Task_task_description_output: + properties: + name: + description: 'The name of the output, e.g. predictions' + type: string + predictions: + $ref: '#/components/schemas/Task_task_description_predictions' + type: object + DataQualityList: + properties: + data_qualities_list: + $ref: '#/components/schemas/DataQualityList_data_qualities_list' + type: object + DataUnprocessed_data_unprocessed: + properties: + dataset: + $ref: '#/components/schemas/DataUnprocessed_data_unprocessed_dataset' + type: object + Study: + properties: + study: + $ref: '#/components/schemas/Study_study' + type: object + DataList_data: + properties: + dataset: + type: array + items: + $ref: '#/components/schemas/DataList_data_dataset' + type: object + UserList_users_user: + properties: + username: + description: 'The full user name' + type: string + id: + description: 'The user ID' + type: string + type: object + TaskType_output: + properties: + name: + description: 'The name of the output, e.g. predictions' + type: string + predictions: + $ref: '#/components/schemas/TaskType_predictions' + type: object + RunList_runs_run: + properties: + task_id: + description: 'The ID of the task solved by this run' + type: string + run_id: + description: 'The run ID' + type: string + error_message: + description: 'Error message generated by the run (if any)' + type: string + setup_id: + description: 'Ignore (internal representation of the parameter setting)' + type: string + uploader: + description: 'The ID of the person uploading this run' + type: string + flow_id: + description: 'The ID of the flow used in this run' + type: string + type: object + DataFeatures_data_features: + properties: + feature: + type: array + items: + $ref: '#/components/schemas/DataFeatures_data_features_feature' + type: object + DataQualities_data_qualities_quality: + properties: + name: + description: 'The name of the dataset quality measures' + type: string + value: + description: 'The value for this dataset' + type: string + type: object + inline_response_200_12_flow_tag: + properties: + id: + description: 'ID of the tagged flow' + type: string + type: object + inline_response_200_8_flow_delete: + properties: + id: + description: 'ID of the deleted flow, a positive integer' + type: string + type: object + DataQualities_data_qualities: + properties: + quality: + type: array + items: + $ref: '#/components/schemas/DataQualities_data_qualities_quality' + type: object + EvaluationRequest: + properties: + evaluation_request: + $ref: '#/components/schemas/EvaluationRequest_evaluation_request' + type: object + inline_response_200_18_upload_flow: + properties: + id: + description: 'ID of the uploaded run, a positive integer' + type: string + type: object + SetupList: + properties: + setups: + $ref: '#/components/schemas/SetupList_setups' + type: object + TaskList: + properties: + task: + $ref: '#/components/schemas/TaskList_task' + type: object + inline_response_200_4_task_delete: + properties: + id: + description: 'ID of the deleted task, a positive integer' + type: string + type: object + Task_task_description_data_set: + properties: + data_set_id: + description: 'The id of the dataset' + type: string + target_feature: + description: 'The name of the target feature for this task' + type: string + type: object + EvaluationList: + properties: + evaluations: + $ref: '#/components/schemas/EvaluationList_evaluations' + type: object + Run_run_description: + properties: + setup_string: + description: 'Configuration of the flow as a string, to be interpreted by the flow, its library, or command line interface.' + type: string + task_type: + description: 'The type of task solved by this run (e.g., classification)' + type: string + task_id: + description: 'The id of the task solved by this run' + type: string + task_evaluation_measure: + description: 'The evaluation measure that is supposed to be optimized in the task, if any' + type: string + uploader_name: + description: 'The name of the uploader of the run' + type: string + input_data: + $ref: '#/components/schemas/Run_run_description_input_data' + tag: + description: 'Tags added by OpenML users. Includes study tags in the form `study_1`' + type: array + items: + type: string + output_data: + $ref: '#/components/schemas/Run_run_description_output_data' + uploader: + description: 'The uploader of the run' + type: string + flow_id: + description: 'The id of the flow used in this run' + type: string + flow_name: + description: 'The name of the flow used in this run' + type: string + id: + description: 'ID of the run, a positive integer' + type: string + parameter_setting: + type: array + items: + $ref: '#/components/schemas/Run_run_description_parameter_setting' + type: object + FlowList: + properties: + flows: + $ref: '#/components/schemas/FlowList_flows' + type: object + inline_response_200_19_run_tag: + properties: + id: + description: 'ID of the tagged run' + type: string + type: object + Study_study_data: + properties: + data_id: + type: array + items: + type: string + type: object + inline_response_200_data_delete: + properties: + id: + description: 'ID of the deleted dataset, a positive integer' + type: string + type: object + RunTrace_trace: + properties: + trace_iteration: + type: array + items: + $ref: '#/components/schemas/RunTrace_trace_trace_iteration' + run_id: + description: 'run ID' + type: string + type: object + inline_response_200_7_task_untag: + properties: + id: + description: 'ID of the untagged task' + type: string + type: object + Data: + properties: + data_set_description: + $ref: '#/components/schemas/Data_data_set_description' + type: object + Task_task_description_evaluation_measures: + properties: + evaluation_measure: + description: 'The evaluation measure to optimize in this task' + type: string + type: object + SetupList_setups_parameter: + properties: + default_value: + description: 'The parameter''s default value' + type: string + data_type: + description: 'The parameter''s data type' + type: string + value: + description: 'The parameter value in this setup' + type: string + parameter_name: + description: 'The parameter''s short name' + type: string + full_name: + description: 'The parameter''s full name' + type: string + flow_id: + description: 'The (sub)flow ID' + type: string + flow_name: + description: 'The (sub)flow name' + type: string + id: + description: 'The parameter ID' + type: string + type: object + TaskList_task_input: + properties: + name: + description: 'The name of the input' + type: string + value: + description: 'The value of the input' + type: string + type: object + StudyList_study_list: + properties: + study: + type: array + items: + $ref: '#/components/schemas/StudyList_study_list_study' + type: object + Study_study_tag: + properties: + write_access: + description: 'The write access level of the study (e.g. public)' + type: string + name: + description: 'The name of the study (e.g. study_1)' + type: string + type: object + Flow: + properties: + flow_description: + $ref: '#/components/schemas/Flow_flow_description' + type: object + Run_run_description_parameter_setting: + properties: + name: + description: 'The name of the parameter' + type: string + value: + description: 'The value of the parameter used' + type: string + type: object + EvaluationRequest_evaluation_request_run: + properties: + setup_id: + description: 'ID of the setup, a positive integer' + type: string + upload_time: + description: 'The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss' + type: string + uploader: + description: 'ID of the uploader, a positive integer' + type: string + task_id: + description: 'ID of the task, a positive integer' + type: string + run_id: + description: 'ID of the run, a positive integer' + type: string + type: object + Error: + properties: + message: + type: string + code: + type: integer + additional_message: + type: string + type: object + EstimationProcedureList_estimationprocedures_estimationprocedure: + properties: + name: + description: 'The estimation procedure name, e.g. ''10 fold Crossvalidation''' + type: string + folds: + description: 'The number of cross-validation folds, e.g. ''10''' + type: string + stratified_sampling: + description: 'Whether or not the sampling is stratified, ''true'' or ''false''' + type: string + ttid: + description: 'The task type ID' + type: string + repeats: + description: 'The number of repeats, e.g. ''10''' + type: string + type: + description: 'The estimation procedure type, e.g. ''crossvalidation''' + type: string + id: + description: 'The estimation procedure ID' + type: string + type: object + TaskTypeList_task_types: + properties: + task_type: + type: array + items: + $ref: '#/components/schemas/TaskTypeList_task_types_task_type' + type: object + TaskList_task_task: + properties: + status: + description: 'The status of the source dataset, active, in_preparation, or deactivated' + type: string + task_type: + description: 'The type of task (e.g. Supervised Classificationr)' + type: string + name: + description: 'The name of the source dataset' + type: string + task_id: + description: 'The ID of the task' + type: string + format: + description: 'The format of the source dataset' + type: string + did: + description: 'The id of the source dataset' + type: string + tag: + type: array + items: + type: string + input: + type: array + items: + $ref: '#/components/schemas/TaskList_task_input' + quality: + type: array + items: + $ref: '#/components/schemas/TaskList_task_quality' + type: object + inline_response_200_20_run_untag: + properties: + id: + description: 'ID of the untagged run' + type: string + type: object + StudyList: + properties: + study_list: + $ref: '#/components/schemas/StudyList_study_list' + type: object + Study_study: + properties: + runs: + $ref: '#/components/schemas/Study_study_runs' + tasks: + $ref: '#/components/schemas/Study_study_tasks' + name: + description: 'The name of the study' + type: string + creator: + description: 'A comma-separated list of the study creators' + type: string + flows: + $ref: '#/components/schemas/Study_study_flows' + creation_date: + description: 'The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss' + type: string + alias: + description: 'The alias of the study' + type: string + tag: + $ref: '#/components/schemas/Study_study_tag' + main_entity_type: + description: 'The type of entity collected in the study (e.g. task or run)' + type: string + data: + $ref: '#/components/schemas/Study_study_data' + id: + description: 'The ID of the study' + type: string + type: object + inline_response_200_25_upload_study: + properties: + id: + description: 'ID of the uploaded study, a positive integer' + type: string + type: object + EvaluationList_evaluations_evaluation: + properties: + function: + description: 'The name of the evaluation function' + type: string + task_id: + description: 'The ID of the tasks solved by this run' + type: string + run_id: + description: 'The run ID' + type: string + array_data: + description: 'For structured evaluation measures, an array of evaluation values (e.g. per-class predictions, evaluation matrices,...)' + type: string + value: + description: 'The outcome of the evaluation' + type: string + flow_id: + description: 'The ID of the flow used by this run' + type: string + type: object + EstimationProcedureList: + properties: + estimationprocedures: + $ref: '#/components/schemas/EstimationProcedureList_estimationprocedures' + type: object + DataQualityList_data_qualities_list: + properties: + quality: + type: array + items: + type: string + type: object + Study_study_flows: + properties: + flow_id: + type: array + items: + type: string + type: object + StudyList_study_list_study: + properties: + alias: + description: 'The alias of the study' + type: string + creation_date: + description: 'The datetime that the dataset was uploaded, format yyyy-MM-dd HH:mm:ss' + type: string + creator: + description: 'A comma-separated list of the study creators' + type: string + id: + description: 'The ID of the study' + type: string + name: + description: 'The name of the study' + type: string + type: object + Run_run_description_input_data: + properties: + dataset: + $ref: '#/components/schemas/Run_run_description_input_data_dataset' + type: object + TaskTypeList_task_types_task_type: + properties: + description: + description: 'A description of the task type' + type: string + creator: + description: 'A comma-separated list of the task type creators' + type: string + id: + description: 'The ID of the task type' + type: string + name: + description: 'The name of the task type' + type: string + type: object + EvaluationMeasureList_evaluation_measures: + properties: + measures: + $ref: '#/components/schemas/EvaluationMeasureList_evaluation_measures_measures' + type: object + TaskType_predictions: + properties: + feature: + type: array + items: + $ref: '#/components/schemas/Task_task_description_predictions_feature' + format: + description: 'The format of the predictions, e.g. ARFF' + type: string + type: object + Flow_flow_description_parameter: + properties: + default_value: + description: 'The default value of the parameter' + type: string + name: + description: 'The name of the parameter' + type: string + data_type: + description: 'The data type of the parameter' + type: string + description: + description: 'A description of the parameter' + type: string + type: object + RunTrace_trace_trace_iteration: + properties: + setup_string: + description: 'A JSON representation of the setup (configuration)' + type: string + repeat: + description: 'The number of the repeat in the outer cross-valudation' + type: string + selected: + description: 'Whether this setup was selected as the best one (true or false)' + type: string + iteration: + description: 'A number of the optimization iteration' + type: string + fold: + description: 'The number of the fold in the inner cross-validation' + type: string + evaluation: + description: 'The evaluation score of the setup' + type: string + type: object + EvaluationMeasureList: + properties: + evaluation_measures: + $ref: '#/components/schemas/EvaluationMeasureList_evaluation_measures' + type: object + SetupList_setups: + properties: + setup: + type: array + items: + $ref: '#/components/schemas/SetupList_setups_setup' + type: object + TaskList_task: + properties: + task: + type: array + items: + $ref: '#/components/schemas/TaskList_task_task' + type: object + SetupList_setups_setup: + properties: + setup_id: + description: 'The setup ID' + type: string + parameter: + type: array + items: + $ref: '#/components/schemas/SetupList_setups_parameter' + flow_id: + description: 'The ID of the flow used by this run' + type: string + type: object + Task_task_description_estimation_procedure_parameter: + properties: + name: + description: 'The name of the parameter' + type: string + value: + description: 'The value of the parameter' + type: string + type: object + RunList_runs: + properties: + run: + type: array + items: + $ref: '#/components/schemas/RunList_runs_run' + type: object + Study_study_tasks: + properties: + task_id: + type: array + items: + type: string + type: object + inline_response_200_1_upload_data_set: + properties: + id: + description: 'ID of the uploaded dataset, a positive integer' + type: string + type: object + Setup_setup_parameters_parameter_setting: + properties: + default_value: + description: 'The default value of the parameter used' + type: string + value: + description: 'The value of the parameter used' + type: string + data_type: + description: 'The data type of the hyperparameter value' + type: string + full_name: + description: 'The full name of the hyperparameter' + type: string + parameter_name: + description: 'The short name of the hyperparameter' + type: string + type: object + DataQualities: + properties: + data_qualities: + $ref: '#/components/schemas/DataQualities_data_qualities' + type: object diff --git a/openapi/unusedSchemas.py b/openapi/unusedSchemas.py new file mode 100644 index 000000000..5cf8cc3e1 --- /dev/null +++ b/openapi/unusedSchemas.py @@ -0,0 +1,55 @@ +import json + +with open('swagger.json',) as f: + data = json.load(f) + +schemasAvailable = list() +schemasReferenced = set() +for k,v in data.items(): + if k=="components": + for k2,v2 in v["schemas"].items(): + schemasAvailable.append(k2) + elif k=="paths": + for k2,v2 in v.items(): + for k3,v3 in v2.items(): + if "parameters" in v3: + for x in v3["parameters"]: + if "$ref" in x["schema"]: + schemasReferenced.add(x["schema"]["$ref"][21:]) + for k4,v4 in v3["responses"].items(): + cur = v4["content"]["application/json"]["schema"] + if "$ref" in cur: + schemasReferenced.add(cur["$ref"][21:]) + if "properties" in cur: + for x,y in cur["properties"].items(): + schemasReferenced.add(y["$ref"][21:]) + +schemasIndirectlyReferenced = set() +schemasIndirectlyReferenced.update(schemasReferenced) + +schemasReferencedQueue = list(schemasReferenced) + +while len(schemasReferencedQueue) > 0: + ele = schemasReferencedQueue[0] + schemasReferencedQueue.remove(ele) + schemasIndirectlyReferenced.add(ele) + for k,v in data["components"]["schemas"][ele]["properties"].items(): + if "$ref" in v: + schemaName = v["$ref"][21:] + if not (schemaName in schemasIndirectlyReferenced): + schemasReferencedQueue.append(schemaName) + if "items" in v and "$ref" in v["items"]: + schemaName = v["items"]["$ref"][21:] + if not (schemaName in schemasIndirectlyReferenced): + schemasReferencedQueue.append(schemaName) + +print("Schemas listed: ", len(schemasAvailable)) +print("Schemas directly referenced: ", len(schemasReferenced)) +print("Schemas (in)directly referenced in total: ", len(schemasIndirectlyReferenced)) + +for e in schemasIndirectlyReferenced: + schemasAvailable.remove(e) + +print("Found ", len(schemasAvailable), " unused schemas: ") +for s in schemasAvailable: + print(s) \ No newline at end of file diff --git a/openml_OS/controllers/Api.php b/openml_OS/controllers/Api.php index 43eb01b8b..12a529d4e 100644 --- a/openml_OS/controllers/Api.php +++ b/openml_OS/controllers/Api.php @@ -1,12 +1,2132 @@ diff --git a/openml_OS/models/api/v1/Api_data.php b/openml_OS/models/api/v1/Api_data.php index c2c52de77..fb94eb7cf 100644 --- a/openml_OS/models/api/v1/Api_data.php +++ b/openml_OS/models/api/v1/Api_data.php @@ -1,4 +1,5 @@ outputFormat = $format; $getpost = array('get','post'); - if (count($segments) >= 1 && $segments[0] == 'list') { array_shift($segments); $this->data_list($segments); @@ -43,6 +43,7 @@ function bootstrap($format, $segments, $request_type, $user_id) { } $order_values = array('random', 'normal'); + if (count($segments) == 3 && $segments[0] == 'unprocessed' && is_numeric($segments[1]) && in_array($segments[2], $order_values)) { $this->data_unprocessed($segments[1], $segments[2]); return; @@ -121,12 +122,12 @@ function bootstrap($format, $segments, $request_type, $user_id) { } if (count($segments) == 1 && $segments[0] == 'tag' && $request_type == 'post') { - $this->entity_tag_untag('dataset', $this->input->post('data_id'), $this->input->post('tag'), false, 'data'); + $this->data_tag($this->input->post('data_id'), $this->input->post('tag')); return; } if (count($segments) == 1 && $segments[0] == 'untag' && $request_type == 'post') { - $this->entity_tag_untag('dataset', $this->input->post('data_id'), $this->input->post('tag'), true, 'data'); + $this->data_untag($this->input->post('data_id'), $this->input->post('tag')); return; } @@ -143,21 +144,244 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->returnError(100, $this->version); } + /** + *@OA\Post( + * path="/data/tag", + * tags={"data"}, + * summary="Tag a dataset", + * description="Tags a dataset.", + * @OA\Parameter( + * name="data_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the dataset.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * description="Api key to authenticate the user", + * required=true, + * @OA\Schema( + * type="string" + * ) + * ), + * @OA\Response( + * response=200, + * description="The id of the tagged dataset", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="data_tag", + * ref="#/components/schemas/inline_response_200_2_data_tag", + * ), + * example={ + * "data_tag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function data_tag($data_id, $tag) { + $this->data_tag_untag($data_id, $tag, false); + } + + /** + *@OA\Post( + * path="/data/untag", + * tags={"data"}, + * summary="Untag a dataset", + * description="Untags a dataset.", + * @OA\Parameter( + * name="data_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the dataset.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The ID of the untagged dataset", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="data_untag", + * ref="#/components/schemas/inline_response_200_3_data_untag", + * ), + * example={ + * "data_untag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function data_untag($data_id, $tag) { + $this->data_tag_untag($data_id, $tag, true); + } + + private function data_tag_untag($data_id,$tag, $do_untag) { + // forward action to superclass + $this->entity_tag_untag('dataset', $data_id, $tag, $do_untag, 'data'); + } + + /** + *@OA\Get( + * path="/data/list/{filters}", + * tags={"data"}, + * summary="List and filter datasets", + * description="List datasets, possibly filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/data/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all datasets that match the constraints.", + * @OA\Parameter( + * name="filters", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Any combination of these filters + /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified. + /status/{status} - returns only datasets with a given status, either 'active', 'deactivated', or 'in_preparation'. + /tag/{tag} - returns only datasets tagged with the given tag. + /{data_quality}/{range} - returns only tasks for which the underlying datasets have certain qualities. {data_quality} can be data_id, data_name, data_version, number_instances, number_features, number_classes, number_missing_values. {range} can be a specific value or a range in the form 'low..high'. Multiple qualities can be combined, as in 'number_instances/0..50/number_features/0..10'. + ", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of datasets with the given task", + * @OA\JsonContent( + * ref="#/components/schemas/DataList", + * example={ + * "data": { + * "dataset": { + * { + * "did":"1", + * "name":"anneal", + * "status":"active", + * "format":"ARFF", + * "quality":{ + * { + * "name":"MajorityClassSize", + * "value":"684" + * }, + * { + * "name":"MaxNominalAttDistinctValues", + * "value":"10.0" + * }, + * { + * "name":"MinorityClassSize" + * ,"value":"0" + * }, + * { + * "name":"NumBinaryAtts", + * "value":"14.0" + * }, + * { + * "name":"NumberOfClasses", + * "value":"6" + * }, + * { + * "name":"NumberOfFeatures", + * "value":"39" + * }, + * { + * "name":"NumberOfInstances", + * "value":"898" + * }, + * { + * "name":"NumberOfInstancesWithMissingValues", + * "value":"0" + * }, + * { + * "name":"NumberOfMissingValues", + * "value":"0" + * }, + * { + * "name":"NumberOfNumericFeatures", + * "value":"6" + * }, + * { + * "name":"NumberOfSymbolicFeatures", + * "value":"32" + * } + * } + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n370 - Illegal filter specified.\n371 - Filter values/ranges not properly specified.\n372 - No results. There where no matches for the given constraints.\n373 - Can not specify an offset without a limit.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_list($segs) { $legal_filters = array('tag', 'status', 'limit', 'offset', 'data_id', 'data_name', 'data_version', 'uploader', 'number_instances', 'number_features', 'number_classes', 'number_missing_values'); - + list($query_string, $illegal_filters) = $this->parse_filters($segs, $legal_filters); if (count($illegal_filters) > 0) { $this->returnError(370, $this->version, $this->openmlGeneralErrorCode, 'Legal filter operators: ' . implode(',', $legal_filters) .'. Found illegal filter(s): ' . implode(', ', $illegal_filters)); return; } - + $illegal_filter_inputs = $this->check_filter_inputs($query_string, $legal_filters, array('tag', 'status', 'data_name', 'number_instances', 'number_features', 'number_classes', 'number_missing_values')); if (count($illegal_filter_inputs) > 0) { $this->returnError(371, $this->version, $this->openmlGeneralErrorCode, 'Filters with illegal values: ' . implode(',', $illegal_filter_inputs)); return; } - + $tag = element('tag', $query_string, null); $name = element('data_name', $query_string, null); $data_id = element('data_id', $query_string, null); @@ -170,7 +394,7 @@ private function data_list($segs) { $nr_feats = element('number_features', $query_string, null); $nr_class = element('number_classes', $query_string, null); $nr_miss = element('number_missing_values', $query_string, null); - + if ($offset && !$limit) { $this->returnError(373, $this->version); return; @@ -189,17 +413,17 @@ private function data_list($segs) { $status_sql_variable = 'IFNULL(`s`.`status`, \'' . $this->config->item('default_dataset_status') . '\')'; $where_status = $status === null ? ' AND ' . $status_sql_variable . ' = "active" ' : ($status != "all" ? ' AND ' . $status_sql_variable . ' = "'. $status . '" ' : ''); $where_total = $where_tag . $where_did . $where_name . $where_version . $where_uploader . $where_insts . $where_feats . $where_class . $where_miss . $where_status; - + $where_limit = $limit === null ? '' : ' LIMIT ' . $limit; if($limit && $offset){ $where_limit = ' LIMIT ' . $offset . ',' . $limit; } - + $sql = 'SELECT d.*, ' . $status_sql_variable . ' AS `status` '. - 'FROM dataset d ' . + 'FROM dataset d ' . 'LEFT JOIN (SELECT `did`, MAX(`status`) AS `status` FROM `dataset_status` GROUP BY `did`) s ON d.did = s.did ' . 'WHERE (visibility = "public" or uploader='.$this->user_id.') '. $where_total . $where_limit; - + $datasets_res = $this->Dataset->query($sql); if( is_array( $datasets_res ) == false || count( $datasets_res ) == 0 ) { $this->returnError( 372, $this->version ); @@ -214,12 +438,12 @@ private function data_list($segs) { } # JvR: This is a BAD idea and this will break in the future, when OpenML grows. - $sql = + $sql = 'SELECT data, quality, value FROM data_quality ' . 'WHERE `data` IN (' . implode(',', array_keys($datasets)) . ') ' . 'AND evaluation_engine_id = ' . $this->config->item('default_evaluation_engine_id') . ' ' . - 'AND quality IN ("' . implode('","', $this->config->item('basic_qualities')) . '") ' . - 'AND value IS NOT NULL ' . + 'AND quality IN ("' . implode('","', $this->config->item('basic_qualities')) . '") ' . + 'AND value IS NOT NULL ' . 'ORDER BY `data`;'; $dq = $this->Data_quality->query($sql); @@ -232,6 +456,60 @@ private function data_list($segs) { $this->xmlContents('data', $this->version, array('datasets' => $datasets)); } + /** + *@OA\Get( + * path="/data/{id}", + * tags={"data"}, + * summary="Get dataset description", + * description="Returns information about a dataset. The information includes the name, information about the creator, URL to download it and more.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the dataset.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A dataset description", + * @OA\JsonContent( + * ref="#/components/schemas/Data", + * example={ + * "data_set_description": { + * "id": "1", + * "name": "anneal", + * "version": "2", + * "description": "...", + * "format": "ARFF", + * "upload_date": "2014-04-06 23:19:20", + * "licence": "Public", + * "url": "https://www.openml.org/data/download/1/dataset_1_anneal.arff", + * "file_id": "1", + * "default_target_attribute": "class", + * "version_label": "2", + * "tag": { + * "study_1", + * "uci" + * }, + * "visibility": "public", + * "original_data_url": "https://www.openml.org/d/2", + * "status": "active", + * "md5_checksum": "d01f6ccd68c88b749b20bbe897de3713" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned\n110 - Please provide data_id.\n111 - Unknown dataset. Data set description with data_id was not found in the database.\n112 - No access granted. This dataset is not shared with you.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data($data_id) { if( $data_id == false ) { $this->returnError( 110, $this->version ); @@ -270,7 +548,7 @@ private function data($data_id) { foreach( $this->xml_fields_dataset['csv'] as $field ) { $dataset->{$field} = getcsv( $dataset->{$field} ); } - + $data_processed = $this->Data_processed->getById(array($data_id, $this->config->item('default_evaluation_engine_id'))); $relevant_fields = array('processing_date', 'error', 'warning'); foreach ($relevant_fields as $field) { @@ -280,7 +558,7 @@ private function data($data_id) { $dataset->{$field} = null; } } - + $dataset->status = $this->config->item('default_dataset_status'); $data_status = $this->Dataset_status->getWhereSingle('did =' . $data_id, 'status_date DESC'); if ($data_status != false) { @@ -289,7 +567,7 @@ private function data($data_id) { $this->xmlContents( 'data-get', $this->version, $dataset ); } - + private function data_reset($data_id) { $dataset = $this->Dataset->getById($data_id); if ($dataset == false) { @@ -301,7 +579,7 @@ private function data_reset($data_id) { $this->returnError(1022, $this->version); return; } - + $result = $this->Data_processed->deleteWhere('`did` = "' . $dataset->did . '" '); if ($result == false) { @@ -311,6 +589,55 @@ private function data_reset($data_id) { $this->xmlContents('data-reset', $this->version, array('dataset' => $dataset)); } + /** + *@OA\Delete( + * path="/data/{id}", + * tags={"data"}, + * summary="Delete dataset", + * description="Deletes a dataset. Upon success, it returns the ID of the deleted dataset.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the dataset.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="ID of the deleted dataset", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="data_delete", + * ref="#/components/schemas/inline_response_200_data_delete", + * ), + * example={ + * "data_delete": { + * "id": "4328" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned\n- 350 - Please provide API key. In order to remove your content, please authenticate.\n- 351 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n- 352 - Dataset does not exists. The data ID could not be linked to an existing dataset.\n- 353 - Dataset is not owned by you. The dataset is owned by another user. Hence you cannot delete it.\n- 354 - Dataset is in use by other content. Can not be deleted. The data is used in tasks or runs. Delete other content before deleting this dataset.\n- 355 - Deleting dataset failed. Deleting the dataset failed. Please contact support team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_delete($data_id) { $dataset = $this->Dataset->getById( $data_id ); @@ -359,6 +686,64 @@ private function data_delete($data_id) { } + /** + *@OA\Post( + * path="/data", + * tags={"data"}, + * summary="Upload dataset", + * description="Uploads a dataset. Upon success, it returns the data id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/data).", + * required=true, + * ), + * @OA\Parameter( + * name="dataset", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="The actual dataset, being an ARFF file.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the uploaded dataset", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_data_set", + * ref="#/components/schemas/inline_response_200_1_upload_data_set", + * ), + * example={ + * "upload_data_set": { + * "id": "4328" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n130 - Problem with file uploading. There was a problem with the file upload.\n131 - Problem validating uploaded description file. The XML description format does not meet the standards.\n132 - Failed to move the files. Internal server error, please contact API administrators.\n133 - Failed to make checksum of datafile. Internal server error, please contact API administrators.\n134 - Failed to insert record in database. Internal server error, please contact API administrators.\n135 - Please provide description xml.\n136 - File failed format verification. The uploaded file is not valid according to the selected file format. Please check the file format specification and try again.\n137 - Please provide API key. In order to share content, please log in or provide your API key.\n138 - Authentication failed. The API key was not valid. Please try to login again, or contact API administrators\n139 - Combination name / version already exists. Leave version out for auto increment\n140 - Both dataset file and dataset url provided. The system is confused since both a dataset file (post) and a dataset url (xml) are provided. Please remove one.\n141 - Neither dataset file or dataset url are provided. Please provide either a dataset file as POST variable, or a dataset url in the description XML.\n142 - Error in processing arff file. Can be a syntax error, or the specified target feature does not exists. For now, we only check on arff files. If a dataset is claimed to be in such a format, and it can not be parsed, this error is returned.\n143 - Suggested target feature not legal. It is possible to suggest a default target feature (for predictive tasks). However, it should be provided in the data.\n144 - Unable to update dataset. The dataset with id could not be found in the database. If you upload a new dataset, unset the id.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_upload() { // get correct description $xsdFile = xsd('openml.data.upload', $this->controller, $this->version); @@ -440,7 +825,7 @@ private function data_upload() { $this->returnError(145, $this->version, $this->openmlGeneralErrorCode, 'Arff error in dataset file: ' . $uploadedFileCheck); return; } - + $to_folder = $this->data_folders['dataset']; $file_id = $this->File->register_uploaded_file($_FILES['dataset'], $to_folder, $this->user_id, 'dataset', $access_control); if ($file_id === false) { @@ -484,7 +869,7 @@ private function data_upload() { 'isOriginal' => 'true', 'file_id' => $file_id ); - + // extract all other necessary info from the XML description $dataset = all_tags_from_xml( $xml->children('oml', true), @@ -505,15 +890,15 @@ private function data_upload() { $this->returnError(134, $this->version); return; } - - // try to move the file to a new directory. If it fails, the dataset is + + // try to move the file to a new directory. If it fails, the dataset is // still valid, but we probably want to make some mechanism to inform administrators if ($file_record->type != 'url') { $subdirectory = floor($id / $this->content_folder_modulo) * $this->content_folder_modulo; $to_folder = $this->data_folders['dataset'] . '/' . $subdirectory . '/' . $id . '/'; $this->File->move_file($file_id, $to_folder); } - + // try making the ES stuff try { // update elastic search index. @@ -538,7 +923,49 @@ private function data_upload() { // create $this->xmlContents('data-upload', $this->version, array('id' => $id)); } - + + /** + *@OA\Post( + * path="/data/status/update/", + * tags={"data"}, + * summary="Change the status of a dataset", + * description="Change the status of a dataset, either 'active' or 'deactivated'", + * @OA\Parameter( + * name="data_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the dataset.", + * required=true, + * ), + * @OA\Parameter( + * name="status", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="The status on which to filter the results, either 'active' or 'deactivated'.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n691 - Illegal status\n692 - Dataset does not exists\n693 - Dataset is not owned by you\n694 - Illegal status transition\n695 - Status update failed\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function status_update($data_id, $status) { // in_preparation is not a legal status to change to $legal_status = array('active', 'deactivated'); @@ -546,7 +973,7 @@ private function status_update($data_id, $status) { $this->returnError(691, $this->version); return; } - + $dataset = $this->Dataset->getById($data_id); if ($dataset == false) { $this->returnError(692, $this->version); @@ -557,12 +984,12 @@ private function status_update($data_id, $status) { $this->returnError(693, $this->version); return; } - + if ($status == 'active' && !$this->user_has_admin_rights) { $this->returnError(696, $this->version); return; } - + $status_record = $this->Dataset_status->getWhereSingle('did = ' . $data_id, 'status DESC'); $in_preparation = $this->config->item('default_dataset_status'); if ($status_record == false) { @@ -570,14 +997,14 @@ private function status_update($data_id, $status) { } else { $old_status = $status_record->status; } - + $record = array( 'did' => $data_id, - 'status' => $status, + 'status' => $status, 'status_date' => now(), 'user_id' => $this->user_id ); - + if ( ($old_status == $in_preparation && $status == 'active') || ($old_status == $in_preparation && $status == 'deactivated') || @@ -586,10 +1013,10 @@ private function status_update($data_id, $status) { $this->Dataset_status->insert($record); } elseif ($old_status == 'deactivated' && $status == 'active') { $this->Dataset_status->delete(array($data_id, 'deactivated')); - + // see if the dataset is still active $status_record = $this->Dataset_status->getWhereSingle('did = ' . $data_id, 'status DESC'); - + $result = true; if (!$status_record || $status_record->status != 'active') { $result = $this->Dataset_status->insert($record); @@ -602,10 +1029,87 @@ private function status_update($data_id, $status) { $this->returnError(694, $this->version); return; } - + $this->xmlContents('data-status-update', $this->version, array('did' => $data_id, 'status' => $status)); } + /** + *@OA\Get( + * path="/data/features/{id}", + * tags={"data"}, + * summary="Get data features", + * description="Returns the features of a dataset.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the dataset.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="All the features of the dataset", + * @OA\JsonContent( + * ref="#/components/schemas/DataFeatures", + * example={ + * "data_features": { + * "feature": { + * { + * "index": "0", + * "name": "sepallength", + * "data_type": "numeric", + * "is_target": "false", + * "is_ignore": "false", + * "is_row_identifier": "false" + * }, + * { + * "index": "1", + * "name": "sepalwidth", + * "data_type": "numeric", + * "is_target": "false", + * "is_ignore": "false", + * "is_row_identifier": "false" + * }, + * { + * "index": "2", + * "name": "petallength", + * "data_type": "numeric", + * "is_target": "false", + * "is_ignore": "false", + * "is_row_identifier": "false" + * }, + * { + * "index": "3", + * "name": "petalwidth", + * "data_type": "numeric", + * "is_target": "false", + * "is_ignore": "false", + * "is_row_identifier": "false" + * }, + * { + * "index": "4", + * "name": "class", + * "data_type": "nominal", + * "is_target": "true", + * "is_ignore": "false", + * "is_row_identifier": "false" + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n270 - Please provide dataset ID.\n271 - Unknown dataset. Data set with the given data ID was not found (or is not shared with you).\n272 - No features found. The dataset did not contain any features, or we could not extract them.\n273 - Dataset not processed yet. The dataset was not processed yet, features are not yet available. Please wait for a few minutes.\n274 - Dataset processed with error. The feature extractor has run into an error while processing the dataset. Please check whether it is a valid supported file. If so, please contact the API admins.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_features($data_id) { $dataset = $this->Dataset->getById($data_id); if ($dataset === false) { @@ -637,12 +1141,12 @@ private function data_features($data_id) { } } $dataset->index_values = $index_values; - + if ($data_processed->error && $dataset->features === false) { $this->returnError(274, $this->version); return; } - + if ($dataset->features === false) { $this->returnError(272, $this->version); return; @@ -659,6 +1163,39 @@ private function data_features($data_id) { $this->xmlContents('data-features', $this->version, $dataset); } + /** + *@OA\Post( + * path="/data/features", + * tags={"data"}, + * summary="Upload dataset feature description", + * description="Uploads dataset feature description. Upon success, it returns the data id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.features) and an [XML example](https://www.openml.org/api/v1/xml_example/data.features).", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n431 - Dataset already processed\n432 - Please provide description xml\n433 - Problem validating uploaded description file\n434 - Could not find dataset\n436 - Something wrong with XML, check data id and evaluation engine id\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_features_upload() { if (!$this->user_has_admin_rights) { $this->returnError(106, $this->version); @@ -670,11 +1207,11 @@ private function data_features_upload() { $this->returnError(442, $this->version); return; } - + // get description from file upload. Note that we will check the XSD later on (after we have assembled fields for error handling) $description = $_FILES['description']; $xml = simplexml_load_file($description['tmp_name']); - + // precheck XSD (if this pre-check succeeds, we can do database error logging later) if (!($xml->children('oml', true)->{'did'} && $xml->children('oml', true)->{'evaluation_engine_id'})) { $this->returnError(443, $this->version, $this->openmlGeneralErrorCode, 'XML misses basic fields did or evaluation_engine_id'); @@ -693,13 +1230,13 @@ private function data_features_upload() { $this->returnError(444, $this->version); return; } - + $data_processed_record = $this->Data_processed->getById(array($did, $eval_id)); if ($data_processed_record && $data_processed_record->error == null) { $this->returnError(441, $this->version); return; } - + $num_tries = 0; if ($data_processed_record) { $num_tries = $data_processed_record->num_tries; @@ -709,12 +1246,12 @@ private function data_features_upload() { $data = array('did' => $did, 'evaluation_engine_id' => $eval_id, 'user_id' => $this->user_id, - 'processing_date' => now(), + 'processing_date' => now(), 'num_tries' => $num_tries + 1); if ($xml->children('oml', true)->{'error'}) { $data['error'] = htmlentities($xml->children('oml', true)->{'error'}); } - + if (validateXml($description['tmp_name'], xsd('openml.data.features', $this->controller, $this->version), $xmlErrors) == false) { $data['error'] = 'XSD does not comply. XSD errors: ' . $xmlErrors; $success = $this->Data_processed->replace($data); @@ -729,10 +1266,10 @@ private function data_features_upload() { } $this->db->trans_start(); - + # replace is delete then insert again $success = $this->Data_processed->replace($data); - if (!$success) { + if (!$success) { $this->returnError(445, $this->version, $this->openmlGeneralErrorCode, 'Failed to create data processed record. '); return; } @@ -765,7 +1302,7 @@ private function data_features_upload() { if (in_array($feature['name'], $ignores)) { $feature['is_ignore'] = 'true'; } - + if (in_array('ClassDistribution', $feature)) { // check class distributions field json_decode($feature['ClassDistribution']); @@ -775,7 +1312,7 @@ private function data_features_upload() { return; } } - + //actual insert of the feature if (array_key_exists('nominal_value', $feature)) { $nominal_values = $feature['nominal_value']; @@ -783,19 +1320,19 @@ private function data_features_upload() { } else { $nominal_values = false; } - + $result = $this->Data_feature->insert($feature); if (!$result) { $this->db->trans_rollback(); $this->returnError(450, $this->version, $this->openmlGeneralErrorCode, 'feature: ' . $feature['name']); return; } - + if ($nominal_values) { // check the nominal value property foreach ($nominal_values as $value) { $data = array( - 'did' => $did, + 'did' => $did, 'index' => $feature['index'], 'value' => $value ); @@ -806,7 +1343,7 @@ private function data_features_upload() { return; } } - + if ($feature['data_type'] != 'nominal') { // only allowed for nominal values $this->db->trans_rollback(); @@ -837,6 +1374,41 @@ private function data_features_upload() { } } + /** + *@OA\Get( + * path="/data/qualities/list", + * tags={"data"}, + * summary="List all data qualities", + * description="Returns a list of all data qualities in the system.", + * @OA\Response( + * response=200, + * description="A list of data qualities", + * @OA\JsonContent( + * ref="#/components/schemas/DataQualityList", + * example={ + * "data_qualities_list":{ + * "quality":{ + * "NumberOfClasses", + * "NumberOfFeatures", + * "NumberOfInstances", + * "NumberOfInstancesWithMissingValues", + * "NumberOfMissingValues", + * "NumberOfNumericFeatures", + * "NumberOfSymbolicFeatures" + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned\n370 - No data qualities available. There are no data qualities in the system.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_qualities_list() { $result = $this->Quality->allUsed( ); $qualities = array(); @@ -867,6 +1439,79 @@ private function feature_qualities_list() { } + /** + *@OA\Get( + * path="/data/qualities/{id}", + * tags={"data"}, + * summary="Get data qualities", + * description="Returns the qualities of a dataset.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the dataset.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="All the qualities of the dataset", + * @OA\JsonContent( + * ref="#/components/schemas/DataQualities", + * example={ + * "data_qualities": { + * "quality": { + * { + * "name": "ClassCount", + * "value": "3.0" + * }, + * { + * "name": "ClassEntropy", + * "value": "1.584962500721156" + * }, + * { + * "name": "NumberOfClasses", + * "value": "3" + * }, + * { + * "name": "NumberOfFeatures", + * "value": "5" + * }, + * { + * "name": "NumberOfInstances", + * "value": "150" + * }, + * { + * "name": "NumberOfInstancesWithMissingValues", + * "value": "0" + * }, + * { + * "name": "NumberOfMissingValues", + * "value": "0" + * }, + * { + * "name": "NumberOfNumericFeatures", + * "value": "4" + * }, + * { + * "name": "NumberOfSymbolicFeatures", + * "value": "0" + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n360 - Please provide data set ID\n361 - Unknown dataset. The data set with the given ID was not found in the database, or is not shared with you.\n362 - No qualities found. The registered dataset did not contain any calculated qualities.\n363 - Dataset not processed yet. The dataset was not processed yet, no qualities are available. Please wait for a few minutes.\n364 - Dataset processed with error. The quality calculator has run into an error while processing the dataset. Please check whether it is a valid supported file. If so, contact the support team.\n365 - Interval start or end illegal. There was a problem with the interval\nstart or end.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_qualities($data_id, $evaluation_engine_id) { if( $data_id == false ) { $this->returnError( 360, $this->version ); @@ -893,7 +1538,7 @@ private function data_qualities($data_id, $evaluation_engine_id) { $interval_start = false; // $this->input->get( 'interval_start' ); $interval_end = false; // $this->input->get( 'interval_end' ); $interval_size = false; // $this->input->get( 'interval_size' ); - + if($interval_start !== false || $interval_end !== false || $interval_size !== false) { $interval_constraints = ''; if( $interval_start !== false && is_numeric( $interval_start ) ) { @@ -909,7 +1554,7 @@ private function data_qualities($data_id, $evaluation_engine_id) { } else { $dataset->qualities = $this->Data_quality->getWhere('data = "' . $dataset->did . '" AND evaluation_engine_id = ' . $evaluation_engine_id); } - + if($data_processed->error && $dataset->qualities === false) { $this->returnError(364, $this->version, $this->openmlGeneralErrorCode, $data_processed->error); return; @@ -978,6 +1623,39 @@ private function feature_qualities($data_id, $evaluation_engine_id) { $this->xmlContents( 'feature-qualities', $this->version, $dataset ); } + /** + *@OA\Post( + * path="/data/qualities", + * tags={"data"}, + * summary="Upload dataset qualities", + * description="Uploads dataset qualities. Upon success, it returns the data id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.data.qualities) and an [XML example](https://www.openml.org/api/v1/xml_example/data.qualities).", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n381 - Something wrong with XML, please check did and evaluation_engine_id\n382 - Please provide description xml\n383 - Problem validating uploaded description file\n384 - Dataset not processed yet\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_qualities_upload() { if (!$this->user_has_admin_rights) { $this->returnError(106, $this->version); @@ -1084,7 +1762,7 @@ private function data_qualities_upload() { $result = $this->Data_quality->insert_ignore($data); } } - + if ($this->db->trans_status() === FALSE) { $this->db->trans_rollback(); $this->returnError(389, $this->version); @@ -1104,12 +1782,53 @@ private function data_qualities_upload() { } } + /** + *@OA\Get( + * path="/data/unprocessed/{data_engine_id}/{order}", + * tags={"data"}, + * summary="Get a list of unprocessed datasets", + * description="This call is for people running their own dataset processing engines. It returns the details of datasets that are not yet processed by the given processing engine. It doesn't process the datasets, it just returns the dataset info.", + * @OA\Parameter( + * name="data_engine_id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="The ID of the data processing engine. You get this ID when you register a new data processing engine with OpenML. The ID of the main data processing engine is 1.", + * required=true, + * ), + * @OA\Parameter( + * name="order", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="When there are multiple datasets still to process, this defines which ones to return. Options are 'normal' - the oldest datasets, or 'random'.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of unprocessed datasets", + * @OA\JsonContent( + * ref="#/components/schemas/DataUnprocessed", + * example={"data_unprocessed": {"run": {{"did": "1", "status": "deactivated", "version": "2", "name": "anneal", "format": "ARFF"}}}} + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n681 - No unprocessed datasets.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function data_unprocessed($evaluation_engine_id, $order) { if (!$this->user_has_admin_rights) { $this->returnError(106, $this->version); return; } - + $this->db->select('d.*')->from('dataset d'); $this->db->join('data_processed p', 'd.did = p.did AND evaluation_engine_id = ' . $evaluation_engine_id, 'left'); $this->db->where('(p.did IS NULL OR (p.error IS NOT NULL AND p.num_tries < ' . $this->config->item('process_data_tries') . ' AND p.processing_date < "' . now_offset('-' . $this->config->item('process_data_offset')) . '"))'); @@ -1144,6 +1863,65 @@ private function data_unprocessed($evaluation_engine_id, $order) { $this->xmlContents('data-unprocessed', $this->version, array('res' => $result)); } + /** + *@OA\Post( + * path="/data/qualities/unprocessed/{data_engine_id}/{order}", + * tags={"data"}, + * summary="Get a list of datasets with unprocessed qualities", + * description="This call is for people running their own dataset processing engines. It returns the details of datasets for which certain qualities are not yet processed by the given processing engine. It doesn't process the datasets, it just returns the dataset info.", + * @OA\Parameter( + * name="data_engine_id", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="The ID of the data processing engine. You get this ID when you register a new data processing engine with OpenML. The ID of the main data processing engine is 1.", + * required=true, + * ), + * @OA\Parameter( + * name="order", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="When there are multiple datasets still to process, this defines which ones to return. Options are 'normal' - the oldest datasets, or 'random'.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="API key to authenticate the user", + * required=false, + * ), + * @OA\Parameter( + * name="qualities", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Comma-separated list of (at least two) quality names, e.g. 'NumberOfInstances,NumberOfFeatures'.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of unprocessed datasets", + * @OA\JsonContent( + * ref="#/components/schemas/DataUnprocessed", + * example={"data_unprocessed": {"run": {{"did": "1", "status": "deactivated", "version": "2", "name": "anneal", "format": "ARFF"}}}} + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n686 - Please specify the features the evaluation engine wants to calculate (at least 2).\n687 - No unprocessed datasets according to the given set of meta-features.\n688 - Illegal qualities.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function dataqualities_unprocessed($evaluation_engine_id, $order, $feature_attributes = false, $priorityTag = null) { if (!$this->user_has_admin_rights) { $this->returnError(106, $this->version); diff --git a/openml_OS/models/api/v1/Api_estimationprocedure.php b/openml_OS/models/api/v1/Api_estimationprocedure.php index 3ad1709bc..beccb51ba 100644 --- a/openml_OS/models/api/v1/Api_estimationprocedure.php +++ b/openml_OS/models/api/v1/Api_estimationprocedure.php @@ -12,7 +12,7 @@ function __construct() { function bootstrap($format, $segments, $request_type, $user_id) { $this->outputFormat = $format; - + if (count($segments) == 1 && $segments[0] == 'list') { $this->estimationprocedure_list(); return; @@ -41,8 +41,54 @@ private function estimationprocedure($id) { } $this->xmlContents( 'estimationprocedure-get', $this->version, array( 'ep' => $ep ) ); } - private function estimationprocedure_list() { + /** + *@OA\Get( + * path="/estimationprocedure/list", + * tags={"estimationprocedure"}, + * summary="List all estimation procedures", + * description="Returns an array with all model performance estimation procedures in the system.", + * @OA\Response( + * response=200, + * description="A list of estimation procedures", + * @OA\JsonContent( + * ref="#/components/schemas/EstimationProcedureList", + * example={ + * "estimationprocedures": { + * "estimationprocedure": { + * { + * "id":"1", + * "ttid":"1", + * "name":"10-fold Crossvalidation", + * "type":"crossvalidation", + * "repeats":"1", + * "folds":"10", + * "stratified_sampling":"true" + * }, + * { + * "id":"2", + * "ttid":"1", + * "name":"5 times 2-fold Crossvalidation", + * "type":"crossvalidation", + * "repeats":"5", + * "folds":"2", + * "stratified_sampling":"true" + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n500 - No model performance estimation procedures available.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function estimationprocedure_list() { $estimationprocedures = $this->Estimation_procedure->get(); if( $estimationprocedures == false ) { $this->returnError( 500, $this->version ); diff --git a/openml_OS/models/api/v1/Api_evaluation.php b/openml_OS/models/api/v1/Api_evaluation.php index 42e460722..84541a6d0 100644 --- a/openml_OS/models/api/v1/Api_evaluation.php +++ b/openml_OS/models/api/v1/Api_evaluation.php @@ -40,6 +40,47 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->returnError(100, $this->version); } + /** + *@OA\Get( + * path="/evaluation/request/{evaluation_engine_id}/{order}", + * tags={"evaluation"}, + * summary="Get an unevaluated run", + * description="This call is for people running their own evaluation engines. It returns the details of a run that is not yet evaluated by the given evaluation engine. It doesn't evaluate the run, it just returns the run info.", + * @OA\Parameter( + * name="evaluation_engine_id", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="The ID of the evaluation engine. You get this ID when you register a new evaluation engine with OpenML. The ID of the main evaluation engine is 1.", + * required=true, + * ), + * @OA\Parameter( + * name="order", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="When there are multiple runs still to evaluate, this defines which one to return. Options are 'normal' - the oldest run, 'reverse' - the newest run, or 'random' - a random run.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of evaluations descriptions", + * @OA\JsonContent( + * ref="#/components/schemas/EvaluationRequest", + * example={"evaluation_request": {"run": {{"setup_id": "68799271", "upload_time": "2018-04-03 21:05:38", "uploader": "1935", "task_id": "3021", "run_id": "8943712"}}}} + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n100 - Function not valid.\n545 - No unevaluated runs according to the criteria.\n546 - Illegal filter.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function evaluation_request($evaluation_engine_id, $order, $num_requests, $segs) { if (!$this->user_has_admin_rights) { $this->returnError(106, $this->version); @@ -94,6 +135,49 @@ private function evaluation_request($evaluation_engine_id, $order, $num_request } + /** + *@OA\Get( + * path="/evaluation/list/{filters}", + * tags={"evaluation"}, + * summary="List and filter evaluations", + * description="List evaluations, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/evaluation/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all evaluations that match the constraints. A maximum of 10,000 results are returned, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain tasks, flows, setups, uploaders or runs.", + * @OA\Parameter( + * name="filters", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Any combination of these filters + /function/{name} - name of the evaluation measure, e.g. area_under_auc or predictive_accuracy. See the OpenML website for the complete list of measures. + /tag/{tag} - returns only evaluations of runs tagged with the given tag. + /run/{ids} - return only evaluations for specific runs, specified as a comma-separated list of run IDs, e.g. ''1,2,3'' + /task/{ids} - return only evaluations for specific tasks, specified as a comma-separated list of task IDs, e.g. ''1,2,3'' + /flow/{ids} - return only evaluations for specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3'' + /setup/{ids} - return only evaluations for specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3'' + /uploader/{ids} - return only evaluations uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3'' + /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified. + /per_fold/{true,false} - whether or not to return crossvalidation scores per fold. Defaults to 'false'. Setting it to 'true' leads to large numbers of results, use only for very specific sets of runs. + /sort_order/{asc,desc} - sorts the results by the evaluation value, according to the selected evaluation measure (function) + ", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of evaluations descriptions", + * @OA\JsonContent( + * ref="#/components/schemas/EvaluationList", + * example={"evaluations": {"evaluation": {{"function": "area_under_roc_curve", "upload_time": "2014-04-06 23:30:40", "task_id": "68", "run_id": "1", "array_data": "[0,0.99113,0.898048,0.874862,0.791282,0.807343,0.820674]", "value": "0.839359", "uploader": "1", "flow_id": "61"}, {"function": "f_measure", "upload_time": "2014-04-06 23:30:40", "task_id": "68", "run_id": "1", "array_data": "[0,0,0.711934,0.735714,0.601363,0.435678,0.430913]", "value": "0.600026", "uploader": "1", "flow_id": "61"}, {"function": "predictive_accuracy", "upload_time": "2014-04-06 23:30:40", "task_id": "68", "run_id": "1", "array_data": {}, "value": "0.614634", "uploader": "1", "flow_id": "61"}}}} + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n540 - Please provide at least task, flow or setup, uploader or run, to\nfilter results, or limit the number of responses.\n541 - The input parameters (task_id, setup_id, flow_id, run_id, uploader_id) did not meet the constraints (comma separated list of integers).\n542 - There where no results. Check whether there are runs under the given constraint.\n543 - Too many results. Given the constraints, there were still too many results. Please add filters to narrow down the list.\n544 - Illegal filter specified.\n545 - Offset specified without limit.\n546 - Requested result limit too high.\n547 - Per fold can only be set to value 'true' or 'false'.\n548 - Per fold queries are experimental and require a fair amount of filters on resulting run records to keep the query fast (use, e.g., flow, setup, task and uploader filter)\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function evaluation_list($segs, $user_id, $show_params) { $result_limit = 10000; $legal_filters = array('task', 'setup', 'flow', 'uploader', 'run', 'tag', 'limit', 'offset', 'function', 'per_fold', 'sort_order', 'study'); @@ -102,7 +186,7 @@ private function evaluation_list($segs, $user_id, $show_params) { $this->returnError(544, $this->version, $this->openmlGeneralErrorCode, 'Legal filter operators: ' . implode(',', $legal_filters) .'. Found illegal filter(s): ' . implode(', ', $illegal_filters)); return; } - + $illegal_filter_inputs = $this->check_filter_inputs($query_string, $legal_filters, array('tag', 'function', 'per_fold', 'sort_order')); if (count($illegal_filter_inputs) > 0) { $this->returnError(541, $this->version, $this->openmlGeneralErrorCode, 'Filters with illegal values: ' . implode(',', $illegal_filter_inputs)); @@ -126,7 +210,7 @@ private function evaluation_list($segs, $user_id, $show_params) { return; } $per_fold = ($per_fold === 'true') ? true : false; // cast to boolean. we only accept lowercase entrees - + if ($offset && !$limit) { $this->returnError(545, $this->version); return; @@ -139,7 +223,7 @@ private function evaluation_list($segs, $user_id, $show_params) { $this->returnError(549, $this->version); return; } - + if ($study_id) { $study = $this->Study->getById($study_id); if ($study === false || $study->legacy != 'n' || $study->main_entity_type != 'run') { @@ -166,7 +250,7 @@ private function evaluation_list($segs, $user_id, $show_params) { $where_limit = ' LIMIT ' . $offset . ',' . $limit; } $where_task_closed = ' AND (`t`.`embargo_end_date` is NULL OR `t`.`embargo_end_date` < NOW() OR `r`.`uploader` = '.$user_id.')'; - + $where_runs = $where_task . $where_setup . $where_uploader . $where_impl . $where_run . $where_tag . $where_study . $where_task_closed; $where_total = $where_runs . $where_function; @@ -176,17 +260,17 @@ private function evaluation_list($segs, $user_id, $show_params) { //shortcuts if (!$implementation_id) { $sql_test = - 'SELECT count(distinct r.rid) as count ' . - 'FROM run r, task t '. - 'WHERE r.task_id = t.task_id ' . - $where_runs; + 'SELECT count(distinct r.rid) as count ' . + 'FROM run r, task t '. + 'WHERE r.task_id = t.task_id ' . + $where_runs; $count = $this->Evaluation->query($sql_test)[0]->count; } else { $sql_test = - 'SELECT count(distinct r.rid) as count ' . - 'FROM run r, task t, algorithm_setup s ' . - 'WHERE r.setup = s.sid AND r.task_id = t.task_id ' . - $where_runs; + 'SELECT count(distinct r.rid) as count ' . + 'FROM run r, task t, algorithm_setup s ' . + 'WHERE r.setup = s.sid AND r.task_id = t.task_id ' . + $where_runs; $count = $this->Evaluation->query($sql_test)[0]->count; } if ($count > $result_limit) { @@ -200,12 +284,12 @@ private function evaluation_list($segs, $user_id, $show_params) { } } } - + $order_by = null; if ($sort_order) { $order_by = 'ORDER BY `e`.`value` ' . $sort_order; } - + if ($per_fold) { $eval_table = 'evaluation_fold'; $columns = 'NULL as value, NULL as array_data, CONCAT("[", GROUP_CONCAT(e.value), "]") AS `values`'; @@ -222,17 +306,17 @@ private function evaluation_list($segs, $user_id, $show_params) { // TODO: remove dependency on task_inputs and dataset table // TODO (2): transform into subquery where all columns except evaluation_fold are obtained in subquery (along with limit requirements, as MYSQL query optimizer does not seem to understand this query has an upper limit to the number of obtained runs that need to be inspected) $sql = - 'SELECT r.rid, r.task_id, r.start_time, r.uploader, s.implementation_id, s.sid, f.name AS `function`, i.fullName, d.did, d.name, e.evaluation_engine_id, ' . $columns . ' ' . - 'FROM run r, ' . $eval_table . ' e, algorithm_setup s, implementation i, dataset d, task t, task_inputs ti, math_function f ' . - 'WHERE r.setup = s.sid ' . - 'AND e.source = r.rid ' . - 'AND e.function_id = f.id ' . - 'AND s.implementation_id = i.id ' . - 'AND r.task_id = t.task_id ' . - 'AND r.task_id = ti.task_id ' . - 'AND ti.input = "source_data" ' . - 'AND ti.value = d.did ' . $where_total; - + 'SELECT r.rid, r.task_id, r.start_time, r.uploader, s.implementation_id, s.sid, f.name AS `function`, i.fullName, d.did, d.name, e.evaluation_engine_id, ' . $columns . ' ' . + 'FROM run r, ' . $eval_table . ' e, algorithm_setup s, implementation i, dataset d, task t, task_inputs ti, math_function f ' . + 'WHERE r.setup = s.sid ' . + 'AND e.source = r.rid ' . + 'AND e.function_id = f.id ' . + 'AND s.implementation_id = i.id ' . + 'AND r.task_id = t.task_id ' . + 'AND r.task_id = ti.task_id ' . + 'AND ti.input = "source_data" ' . + 'AND ti.value = d.did ' . $where_total; + if ($group_by) { $sql .= $group_by; } @@ -242,14 +326,14 @@ private function evaluation_list($segs, $user_id, $show_params) { if ($where_limit) { $sql .= $where_limit; } - + $res = $this->Evaluation->query($sql); if ($res == false) { $this->returnError(542, $this->version); return; } - + if ($show_params) { # 2 stage query .. unfortunately. Can break when too much results. let's take the damage for now $setup_ids = array(); diff --git a/openml_OS/models/api/v1/Api_evaluationmeasure.php b/openml_OS/models/api/v1/Api_evaluationmeasure.php index 7cde44a37..e3c5aadfe 100644 --- a/openml_OS/models/api/v1/Api_evaluationmeasure.php +++ b/openml_OS/models/api/v1/Api_evaluationmeasure.php @@ -1,4 +1,5 @@ outputFormat = $format; - + if (count($segments) == 1 && $segments[0] == 'list') { $this->evaluationmeasure_list(); return; @@ -23,8 +24,34 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->returnError( 100, $this->version ); } - - + + /** + *@OA\Get( + * path="/evaluationmeasure/list", + * tags={"evaluationmeasure"}, + * summary="List all evaluation measures", + * description="Returns an array with all model evaluation measures in the system.", + * @OA\Response( + * response=200, + * description="A list of evaluation measures", + * @OA\JsonContent( + * ref="#/components/schemas/EvaluationMeasureList", + * example={ + * "evaluation_measures":{ + * "measures":{ + * "measure":{ + * "area_under_roc_curve", + * "average_cost", + * "binominal_test", + * "build_cpu_time" + * } + * } + * } + * } + * ), + * ), + *) + */ private function evaluationmeasure_list() { $data = new stdClass(); $data->measures = $this->Math_function->getWhere( 'functionType = "EvaluationFunction"' ); diff --git a/openml_OS/models/api/v1/Api_flow.php b/openml_OS/models/api/v1/Api_flow.php index 7c1f61f55..142f80e8a 100644 --- a/openml_OS/models/api/v1/Api_flow.php +++ b/openml_OS/models/api/v1/Api_flow.php @@ -1,4 +1,5 @@ entity_tag_untag('implementation', $this->input->post('flow_id'), $this->input->post('tag'), false, 'flow'); + $this->flow_tag($this->input->post('flow_id'), $this->input->post('tag')); return; } if (count($segments) == 1 && $segments[0] == 'untag' && $request_type == 'post') { - $this->entity_tag_untag('implementation', $this->input->post('flow_id'), $this->input->post('tag'), true, 'flow'); + $this->flow_untag($this->input->post('flow_id'), $this->input->post('tag')); return; } @@ -82,7 +83,72 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->returnError( 100, $this->version ); } - + /** + *@OA\Get( + * path="/flow/list/{filters}", + * tags={"flow"}, + * summary="List and filter flows", + * description="List flows, possibly filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/task/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all flows that match the constraints.", + * @OA\Parameter( + * name="filters", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Any combination of these filters + /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, tasks 11..15 will be returned. Both limit and offset need to be specified. + /tag/{tag} - returns only tasks tagged with the given tag. + /uploader/{id} - return only evaluations uploaded by a specific user, specified by user ID. + ", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of flows", + * @OA\JsonContent( + * ref="#/components/schemas/FlowList", + * example={ + * "flows": + * { + * "flow":{ + * { + * "id":"65", + * "full_name":"weka.RandomForest(1)", + * "name":"weka.RandomForest", + * "version":"1", + * "external_version":"Weka_3.7.10_9186", + * "uploader":"1" + * }, + * { + * "id":"66", + * "full_name":"weka.IBk(1)", + * "name":"weka.IBk", + * "version":"1", + * "external_version":"Weka_3.7.10_8034", + * "uploader":"1" + * }, + * { + * "id":"67", + * "full_name":"weka.BayesNet_K2(1)", + * "name":"weka.BayesNet_K2", + * "version":"1", + * "external_version":"Weka_3.7.10_8034", + * "uploader":"1" + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n500 - No results. There where no matches for the given constraints.\n501 - Illegal filter specified.\n502 - Filter values/ranges not properly specified.\n503 - Can not specify an offset without a limit.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function flow_list($segs) { $legal_filters = array('uploader', 'tag', 'limit', 'offset'); @@ -136,7 +202,186 @@ private function flow_list($segs) { $this->xmlContents('implementations', $this->version, array('implementations' => $implementations_res)); } + /** + *@OA\Post( + * path="/flow/tag", + * tags={"flow"}, + * summary="Tag a flow", + * description="Tags a flow.", + * @OA\Parameter( + * name="flow_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the flow.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The id of the tagged flow", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="flow_tag", + * ref="#/components/schemas/inline_response_200_12_flow_tag", + * ), + * example={ + * "flow_tag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function flow_tag($flow_id, $tag) { + $this->flow_tag_untag($flow_id,$tag, false); + } + + /** + *@OA\Post( + * path="/flow/untag", + * tags={"flow"}, + * summary="Untag a flow", + * description="Untags a flow.", + * @OA\Parameter( + * name="flow_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the flow.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The id of the untagged flow", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="flow_untag", + * ref="#/components/schemas/inline_response_200_13_flow_untag", + * ), + * example={ + * "flow_untag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged\nby another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function flow_untag($flow_id, $tag) { + $this->flow_tag_untag($flow_id, $tag, true); + } + + private function flow_tag_untag($flow_id, $tag, $do_untag) { + //forward execution of logic to superclass. + $this->entity_tag_untag('implementation', $flow_id, $tag, $do_untag, 'flow'); + } + + /** + *@OA\Get( + * path="/flow/exists/{name}/{version}", + * tags={"flow"}, + * summary="Check whether flow exists", + * description="Checks whether a flow with the given name and (external) version exists.", + * @OA\Parameter( + * name="name", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="The name of the flow.", + * required=true, + * ), + * @OA\Parameter( + * name="version", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="The external version of the flow", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of flows", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="flow_exists", + * ref="#/components/schemas/inline_response_200_10_flow_exists", + * ), + * example={ + * "flow_exists": { + * "exists": "true", + * "id": "65" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n330 - Mandatory fields not present. Please provide name and external_version.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function flow_exists($name, $external_version) { $similar = false; @@ -154,7 +399,65 @@ private function flow_exists($name, $external_version) { $this->xmlContents( 'implementation-exists', $this->version, $result ); } - // TODO: check what is going wrong with implementation id 1 + /** + *@OA\Get( + * path="/flow/{id}", + * tags={"flow"}, + * summary="Get flow description", + * description="Returns information about a flow. The information includes the name, information about the creator, dependencies, parameters, run instructions and more.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="ID of the flow.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A flow description", + * @OA\JsonContent( + * ref="#/components/schemas/Flow", + * example={ + * "flow": { + * "id":"100", + * "uploader":"1", + * "name":"weka.J48", + * "version":"2", + * "external_version":"Weka_3.7.5_9117", + * "description":"...", + * "upload_date":"2014-04-23 18:00:36", + * "language":"Java", + * "dependencies":"Weka_3.7.5", + * "parameter": { + * { + * "name":"A", + * "data_type":"flag", + * "default_value":{}, + * "description":"Laplace smoothing..." + * }, + * { + * "name":"C", + * "data_type":"option", + * "default_value":"0.25", + * "description":"Set confidence threshold..." + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n180 - Please provide flow id.\n181 - Unknown flow. The flow with the given ID was not found in the database.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + // TODO: check what is going wrong with implementation id 1 private function flow($id) { if( $id == false ) { $this->returnError( 180, $this->version ); @@ -171,6 +474,64 @@ private function flow($id) { $this->xmlContents( 'implementation-get', $this->version, array( 'source' => $implementation ) ); } + /** + *@OA\Post( + * path="/flow", + * tags={"flow"}, + * summary="Upload a flow", + * description="Uploads a flow. Upon success, it returns the flow id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the flow. Only name and description are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.implementation.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/flow).", + * required=true, + * ), + * @OA\Parameter( + * name="flow", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="The actual flow, being a source (or binary) file.", + * required=false, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the uploaded flow", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_flow", + * ref="#/components/schemas/inline_response_200_9_upload_flow", + * ), + * example={ + * "upload_flow": { + * "id": "2520" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n160 - Error in file uploading. There was a problem with the file upload.\n161 - Please provide description xml.\n163 - Problem validating uploaded description file. The XML description format does not meet the standards.\n164 - Flow already stored in database. Please change name or version number\n165 - Failed to insert flow. There can be many causes for this error. If you included the implements field, it should be an existing entry in the algorithm or math_function table. Otherwise it could be an internal server error. Please contact API support team.\n166 - Failed to add flow to database. Internal server error, please contact API administrators\n167 - Illegal files uploaded. An non required file was uploaded.\n168 - The provided md5 hash equals not the server generated md5 hash of the file.\n169 - Please provide API key. In order to share content, please authenticate and provide API key.\n170 - Authentication failed. The API key was not valid. Please try to login again, or contact API administrators\n171 - Flow already exists. This flow is already in the database\n172 - XSD not found. Please contact API support team\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function flow_upload() { if(isset($_FILES['source']) && $_FILES['source']['error'] == 0) { @@ -297,6 +658,55 @@ private function flow_upload() { $this->xmlContents( 'implementation-upload', $this->version, $implementation ); } + /** + *@OA\Delete( + * path="/flow/{id}", + * tags={"flow"}, + * summary="Delete a flow", + * description="Deletes a flow. Upon success, it returns the ID of the deleted flow.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the flow.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="API key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="ID of the deleted flow", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="flow_delete", + * ref="#/components/schemas/inline_response_200_8_flow_delete", + * ), + * example={ + * "flow_delete": { + * "id": "4328" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n320 - Please provide API key. In order to remove your content, please authenticate.\n321 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n322 - Flow does not exists. The flow ID could not be linked to an existing flow.\n323 - Flow is not owned by you. The flow is owned by another user. Hence you cannot delete it.\n324 - Flow is in use by other content. Can not be deleted. The flow is used in runs, evaluations or as a component of another flow. Delete other content before deleting this flow.\n325 - Deleting flow failed. Deleting the flow failed. Please contact\nsupport team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function flow_delete($flow_id) { $implementation = $this->Implementation->getById($flow_id); diff --git a/openml_OS/models/api/v1/Api_run.php b/openml_OS/models/api/v1/Api_run.php index bf014e4f8..be5add8a5 100644 --- a/openml_OS/models/api/v1/Api_run.php +++ b/openml_OS/models/api/v1/Api_run.php @@ -1,6 +1,11 @@ entity_tag_untag('run', $this->input->post('run_id'), $this->input->post('tag'), false, 'run'); + $this->run_tag($this->input->post('run_id'), $this->input->post('tag')); return; } if (count($segments) == 1 && $segments[0] == 'untag' && $request_type == 'post') { - $this->entity_tag_untag('run', $this->input->post('run_id'), $this->input->post('tag'), true, 'run'); + $this->run_untag($this->input->post('run_id'), $this->input->post('tag')); return; } @@ -101,7 +106,170 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->returnError( 100, $this->version ); } + /** + *@OA\Post( + * path="/run/tag", + * tags={"run"}, + * summary="Tag a run", + * description="Tags a run.", + * @OA\Parameter( + * name="run_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the run.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The id of the tagged run", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="run_tag", + * ref="#/components/schemas/inline_response_200_19_run_tag", + * ), + * example={ + * "run_tag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function run_tag($run_id, $tag) { + $this->entity_tag_untag(self::ENTITY_TYPE, $run_id, $tag, false, self::ENTITY_SPECIAL_NAME); + } + + /** + *@OA\Post( + * path="/run/untag", + * tags={"run"}, + * summary="Untag a run", + * description="Untags a run.", + * @OA\Parameter( + * name="run_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the run.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The id of the untagged run", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="run_untag", + * ref="#/components/schemas/inline_response_200_20_run_untag", + * ), + * example={ + * "run_untag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function run_untag($run_id, $tag) { + $this->entity_tag_untag(self::ENTITY_TYPE, $run_id, $tag, true, self::ENTITY_SPECIAL_NAME); + } + /** + *@OA\Get( + * path="/run/list/{filters}", + * tags={"run"}, + * summary="List and filter runs", + * description="List runs, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/run/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all runs that match the constraints. A maximum of 10,000 results are returned, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain tasks, flows, setups, or uploaders.", + * @OA\Parameter( + * name="filters", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Any combination of these filters + /tag/{tag} - return only runs tagged with the given tag. + /run/{ids} - return only specific runs, specified as a comma-separated list of run IDs, e.g. ''1,2,3'' + /task/{ids} - return only runs on specific tasks, specified as a comma-separated list of task IDs, e.g. ''1,2,3'' + /flow/{ids} - return only runs on specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3'' + /setup/{ids} - return only runs with specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3'' + /uploader/{ids} - return only runs uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3'' + /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified. + ", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of runs descriptions", + * @OA\JsonContent( + * ref="#/components/schemas/RunList", + * example={"runs": {"run": {{"upload_time": "2014-04-06 23:30:40", "task_id": "28", "run_id": "100", "error_message": {}, "setup_id": "12", "uploader": "1", "flow_id": "67"}, {"upload_time": "2014-04-06 23:30:40", "task_id": "48", "run_id": "101", "error_message": {}, "setup_id": "6", "uploader": "1", "flow_id": "61"}, {"upload_time": "2014-04-06 23:30:40", "task_id": "41", "run_id": "102", "error_message": {}, "setup_id": "3", "uploader": "1", "flow_id": "58"}}}} + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n510 - Please provide at least task, flow or setup, uploader or run, to filter results, or limit the number of responses. The number of runs is huge. Please limit the result space.\n511 - Input not safe. The input parameters (task_id, setup_id, flow_id, run_id, uploader_id) did not meet the constraints (comma separated list of integers).\n512 - There where no results. Check whether there are runs under the given constraint.\n513 - Too many results. Given the constraints, there were still too many results. Please add filters to narrow down the list.\n514 - Illegal filter specified.\n515 - Offset specified without limit.\n516 - Requested result limit too high.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run_list($segs, $user_id) { $result_limit = 10000; $legal_filters = array('task', 'setup', 'flow', 'uploader', 'run', 'tag', 'limit', 'offset', 'task_type', 'study', 'show_errors'); @@ -203,7 +371,118 @@ private function run_list($segs, $user_id) { $this->xmlContents('runs', $this->version, array('runs' => $res)); } - + /** + *@OA\Get( + * path="/run/{id}", + * tags={"run"}, + * summary="Get run description", + * description="Returns information about a run. The information includes the name, information about the creator, dependencies, parameters, run instructions and more.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="ID of the run.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A run description", + * @OA\JsonContent( + * ref="#/components/schemas/Run", + * example={ + * "run": { + * "run_id":"100", + * "uploader":"1", + * "uploader_name":"Jan van Rijn", + * "task_id":"28", + * "task_type":"Supervised Classification", + * "task_evaluation_measure":"predictive_accuracy", + * "flow_id":"67", + * "flow_name":"weka.BayesNet_K2(1)", + * "setup_string":"weka.classifiers.bayes.BayesNet -- -D -Q weka.classifiers.bayes.net.search.local.K2 -- -P 1 -S BAYES -E weka.classifiers.bayes.net.estimate.SimpleEstimator -- -A 0.5", + * "parameter_setting": { + * { + * "name":"D", + * "value":"true" + * }, + * { + * "name":"Q", + * "value":"weka.classifiers.bayes.net.search.local.K2" + * }, + * { + * "name":"P", + * "value":"1" + * }, + * { + * "name":"S", + * "value":"BAYES" + * } + * }, + * "input_data": + * { + * "dataset": + * { + * "did":"28", + * "name":"optdigits", + * "url":"https:\\/\\/www.openml.org\\/data\\/download\\/28\\/dataset_28_optdigits.arff" + * } + * }, + * "output_data": + * { + * "file": { + * { + * "did":"48838", + * "file_id":"261", + * "name":"description", + * "url":"https:\\/\\/www.openml.org\\/data\\/download\\/261\\/weka_generated_run935374685998857626.xml" + * }, + * { + * "did":"48839", + * "file_id":"262", + * "name":"predictions", + * "url":"https:\\/\\/www.openml.org\\/data\\/download\\/262\\/weka_generated_predictions576954524972002741.arff" + * } + * }, + * "evaluation": { + * { + * "name":"area_under_roc_curve", + * "flow_id":"4", + * "value":"0.990288", + * "array_data":"[0.99724,0.989212,0.992776,0.994279,0.980578,0.98649,0.99422,0.99727,0.994858,0.976143]" + * }, + * { + * "name":"confusion_matrix", + * "flow_id":"10", + * "array_data":"[[544,1,0,0,7,0,1,0,0,1],[0,511,21,1,0,1,3,1,5,28],[0,7,511,1,0,1,0,3,23,11],[0,2,2,519,0,3,0,12,16,18],[0,3,0,0,528,0,4,21,6,6],[0,1,0,7,5,488,2,0,4,51],[1,7,0,0,2,0,548,0,0,0],[0,2,0,1,9,1,0,545,4,4],[1,25,2,2,3,6,2,1,503,9],[0,7,0,20,16,5,0,19,9,486]]" + * }, + * { + * "name":"f_measure", + * "flow_id":"12", + * "value":"0.922723", + * "array_data":"[0.989091,0.898857,0.935041,0.92431,0.927944,0.918156,0.980322,0.933219,0.895018,0.826531]" + * }, + * { + * "name":"kappa", + * "flow_id":"13", + * "value":"0.913601" + * } + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n220 - Please provide run ID. In order to view run details, please provide the run ID.\n221 - Run not found. The run ID was invalid, run does not exist (anymore).\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run($run_id) { if( $run_id == false ) { $this->returnError( 235, $this->version ); @@ -230,6 +509,55 @@ private function run($run_id) { $this->xmlContents( 'run-get', $this->version, array( 'source' => $run ) ); } + /** + *@OA\Delete( + * path="/run/{id}", + * tags={"run"}, + * summary="Delete run", + * description="Deletes a run. Upon success, it returns the ID of the deleted run.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the run.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="API key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="ID of the deleted run", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="data_delete", + * ref="#/components/schemas/inline_response_200_17_data_delete", + * ), + * example={ + * "run_delete": { + * "id": "2520" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n390 - Please provide API key. In order to remove your content, please authenticate.\n391 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators\n392 - Run does not exists. The run ID could not be linked to an existing run.\n393 - Run is not owned by you. The run was owned by another user. Hence you cannot delete it.\n394 - Deleting run failed. Deleting the run failed. Please contact support team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run_delete($run_id) { $run = $this->Run->getById( $run_id ); @@ -275,7 +603,46 @@ private function run_delete($run_id) { $this->xmlContents( 'run-delete', $this->version, array( 'run' => $run ) ); } - + /** + *@OA\Get( + * path="/run/reset/{id}", + * tags={"run"}, + * summary="Resets a run.", + * description="Removes all run evaluations. When a run is reset, the runs will automatically be evaluated as soon as they are picked up by the evaluation engine again.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Run ID.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the evaluated run", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="run_reset", + * ref="#/components/schemas/inline_response_200_21_upload_flow", + * ), + * example={ + * "run_reset": { + * "id": "2520" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n412 - Run does not exist\n413 - Run is not owned by you\n394 - Resetting run failed\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run_reset($run_id) { $run = $this->Run->getById( $run_id ); @@ -298,6 +665,82 @@ private function run_reset($run_id) { $this->xmlContents( 'run-reset', $this->version, array( 'run' => $run ) ); } + /** + *@OA\Post( + * path="/run", + * tags={"run"}, + * summary="Upload run", + * description="Uploads a run. Upon success, it returns the run id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the dataset. Only name, description, and data format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/run).", + * required=true, + * ), + * @OA\Parameter( + * name="predictions", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="The predictions generated by the run", + * required=true, + * ), + * @OA\Parameter( + * name="model_readable", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="The human-readable model generated by the run", + * required=false, + * ), + * @OA\Parameter( + * name="model_serialized", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="The serialized model generated by the run", + * required=false, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the uploaded run", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_flow", + * ref="#/components/schemas/inline_response_200_18_upload_flow", + * ), + * example={ + * "upload_run": { + * "id": "2520" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n201 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n202 - Please provide run XML.\n203 - Could not validate run xml by XSD. Please double check that the xml is valid.\n204 - Unknown task. The task with the given ID was not found in the database.\n205 - Unknown flow. The flow with the given ID was not found in the database.\n206 - Invalid number of files. The number of uploaded files did not match the number of files expected for the task type\n207 - File upload failed. One of the files uploaded has a problem.\n208 - Error inserting setup record. Please contact api administrators\n210 - Unable to store run. Please contact api administrators.\n211 - Dataset not in database. One of the datasets of the task was not included in database, please contact api administrators.\n212 - Unable to store file. Please contact api administrators.\n213 - Parameter in run xml unknown. One of the parameters provided in the run xml is not registered as parameter for the flow nor its components.\n214 - Unable to store input setting. Please contact API support team.\n215 - Unable to evaluate predictions. Please contact API support team.\n216 - Error thrown by Java Application. Additional information field is provided.\n217 - Error processing output data. Unknown or inconsistent evaluation measure. One of the provided evaluation measures could not be matched with a record in the math_function or flow table.\n218 - Wrong flow associated with run. The flow implements a math_function, which is unable to generate predictions. Please select another flow.\n219 - Error reading the XML document. The XML description file could not be verified.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run_upload() { /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * @@ -600,6 +1043,62 @@ private function run_upload() { $this->xmlContents( 'run-upload', $this->version, $result ); } + /** + *@OA\Get( + * path="/run/trace/{id}", + * tags={"run"}, + * summary="Get run trace", + * description="Returns the optimization trace of run. The trace contains every setup tried, its evaluation, and whether it was selected.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="ID of the run.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A run trace description", + * @OA\JsonContent( + * ref="#/components/schemas/RunTrace", + * example={ + * "trace": { + * "run_id":"573055", + * "trace_iteration": { + * "repeat":"0", + * "fold":"0", + * "repeat":"0", + * "iteration":"0", + * "setup_string":{"parameter_minNumObj": "1", + * "parameter_confidenceFactor": "0.1"}, + * "evaluation":"94.814815", + * "selected": "true" + * }, + * "trace_iteration": { + * "repeat":"0", + * "fold":"0", + * "repeat":"0", + * "iteration":"1", + * "setup_string":{"parameter_minNumObj": "1", + * "parameter_confidenceFactor": "0.25"}, + * "evaluation": "94.074074", + * "selected": "true" + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n570 - No successful trace associated with this run\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run_trace($run_id) { $run = $this->Run->getById($run_id); if ($run === false) { @@ -616,6 +1115,64 @@ private function run_trace($run_id) { $this->xmlContents('run-trace-get', $this->version, array('run_id' => $run_id, 'trace' => $trace)); } + /** + *@OA\Post( + * path="/run/trace/{id}", + * tags={"run"}, + * summary="Upload run trace", + * description="Uploads a run trace. Upon success, it returns the run id.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="ID of the run.", + * required=true, + * ), + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the trace. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.trace) and an [XML example](https://www.openml.org/api/v1/xml_example/run.trace).", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the run with the trace", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_flow", + * ref="#/components/schemas/inline_response_200_23_upload_flow", + * ), + * example={ + * "run_trace": { + * "id": "2520" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n561 - Problem with uploaded trace file.\n562 - Problem validating xml trace file.\n563 - Problem loading xml trace file.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run_trace_upload() { if (!$this->user_has_admin_rights) { $this->returnError(106, $this->version); @@ -666,6 +1223,55 @@ private function run_trace_upload() { $this->xmlContents('run-trace', $this->version, array('run_id' => $run_id)); } + /** + *@OA\Post( + * path="/run/evaluate", + * tags={"run"}, + * summary="Uploads a run evaluation", + * description="Uploads a run evaluation. When successful, it returns the run id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the run evaluation.Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.run.evaluate) and an [XML example](https://www.openml.org/api/v1/xml_example/run.evaluate).", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the evaluated run", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_flow", + * ref="#/components/schemas/inline_response_200_21_upload_flow", + * ), + * example={ + * "run_evaluate": { + * "id": "2520" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n422 - Upload problem description XML\n423 - Problem validating uploaded description file\n424 - Problem opening description xml\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function run_evaluate() { $timestamps = array(microtime(true)); // profiling 0 if (!$this->user_has_admin_rights) { diff --git a/openml_OS/models/api/v1/Api_setup.php b/openml_OS/models/api/v1/Api_setup.php index ca66360d1..fff2dd4bd 100644 --- a/openml_OS/models/api/v1/Api_setup.php +++ b/openml_OS/models/api/v1/Api_setup.php @@ -41,12 +41,12 @@ function bootstrap($format, $segments, $request_type, $user_id) { } if (count($segments) == 1 && $segments[0] == 'tag' && $request_type == 'post') { - $this->entity_tag_untag('algorithm_setup', $this->input->post('setup_id'), $this->input->post('tag'), false, 'setup'); + $this->setup_tag( $this->input->post('setup_id'), $this->input->post('tag')); return; } if (count($segments) == 1 && $segments[0] == 'untag' && $request_type == 'post') { - $this->entity_tag_untag('algorithm_setup', $this->input->post('setup_id'), $this->input->post('tag'), true, 'setup'); + $this->setup_untag($this->input->post('setup_id'), $this->input->post('tag')); return; } @@ -84,6 +84,196 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->returnError( 100, $this->version ); } + /** + *@OA\Post( + * path="/setup/tag", + * tags={"setup"}, + * summary="Tag a setup", + * description="Tags a setup.", + * @OA\Parameter( + * name="setup_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the setup.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The id of the tagged setup", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="flow_tag", + * ref="#/components/schemas/inline_response_200_15_flow_tag", + * ), + * example={ + * "setup_tag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function setup_tag($setup_id, $tag) { + $this->setup_tag_untag($setup_id, $tag, false); + } + + /** + *@OA\Post( + * path="/setup/untag", + * tags={"setup"}, + * summary="Untag a setup", + * description="Untags a setup.", + * @OA\Parameter( + * name="setup_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the setup.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The id of the untagged setup", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="flow_untag", + * ref="#/components/schemas/inline_response_200_16_flow_untag", + * ), + * example={ + * "setup_untag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, flow, run} not found. The provided entity_id {data_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged\nby another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function setup_untag($setup_id, $tag) { + $this->setup_tag_untag($setup_id, $tag, true); + } + + private function setup_tag_untag($setup_id, $tag, $do_untag) { + $this->entity_tag_untag('algorithm_setup', $setup_id, $tag, $do_untag, 'setup'); + } + + /** + *@OA\Get( + * path="/setup/{id}", + * tags={"setup"}, + * summary="Get a hyperparameter setup", + * description="Returns information about a setup. The information includes the list of hyperparameters, with name, value, and default value.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="ID of the hyperparameter setup (configuration). These IDs are stated in run descriptions.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A setup description", + * @OA\JsonContent( + * ref="#/components/schemas/Setup", + * example={ + * "setup_parameters":{ + * "flow_id":"59", + * "parameter":{ + * { + * "full_name":"weka.JRip(1)_F", + * "parameter_name":"F", + * "data_type":"option", + * "default_value":"3", + * "value":"3" + * },{ + * "full_name":"weka.JRip(1)_N", + * "parameter_name":"N", + * "data_type":"option", + * "default_value":"2.0", + * "value":"2.0" + * },{ + * "full_name":"weka.JRip(1)_O", + * "parameter_name":"O", + * "data_type":"option", + * "default_value":"2", + * "value":"2" + * },{ + * "full_name":"weka.JRip(1)_S", + * "parameter_name":"S", + * "data_type":"option", + * "default_value":"1", + * "value":"1" + * }} + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n280 - Please provide setup ID. In order to view setup details, please provide the run ID\n281 - Setup not found. The setup ID was invalid, or setup does not exist (anymore).\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function setup($setup_id) { if($setup_id == false) { $this->returnError(280, $this->version); @@ -105,7 +295,75 @@ private function setup($setup_id) { $this->xmlContents('setup-parameters', $this->version, array('parameters' => $this->parameters, 'setup' => $setup)); } } - + + /** + *@OA\Get( + * path="/setup/list/{filters}", + * tags={"setup"}, + * summary="List and filter setups", + * description="List setups, filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/setup/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all evaluations that match the constraints. A maximum of 1,000 results are returned at a time, an error is returned if the result set is bigger. Use pagination (via limit and offset filters), or limit the results to certain flows, setups, or tags.", + * @OA\Parameter( + * name="filters", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Any combination of these filters + /tag/{tag} - returns only setups tagged with the given tag. + /flow/{ids} - return only setups for specific flows, specified as a comma-separated list of flow IDs, e.g. ''1,2,3'' + /setup/{ids} - return only specific setups, specified as a comma-separated list of setup IDs, e.g. ''1,2,3'' + /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified. + ", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of setup descriptions", + * @OA\JsonContent( + * ref="#/components/schemas/SetupList", + * example={ + * "setups": { + * "setup": { + * { + * "setup_id":"10", + * "flow_id":"65", + * "parameter": { + * { + * "id":"4144", + * "flow_id":"65", + * "flow_name":"weka.RandomForest", + * "full_name":"weka.RandomForest(1)_I", + * "parameter_name":"I", + * "data_type":"option", + * "default_value":"10", + * "value":"10" + * }, + * { + * "id":"4145", + * "flow_id":"65", + * "flow_name":"weka.RandomForest", + * "full_name":"weka.RandomForest(1)_K", + * "parameter_name":"K", + * "data_type":"option", + * "default_value":"0", + * "value":"0" + * } + * } + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n670 - Please specify at least one filter.\n671 - Illegal filter.\n672 - Illegal filter input.\n673 - Result set too big. Please use one of the filters or the limit option.\n674 - No results, please check the filter.\n675 - Cannot specify offset without limit.\n676 - Requested result limit too high.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ function setup_list($segs) { $result_limit = 1000; $legal_filters = array('flow', 'setup', 'limit', 'offset', 'tag'); @@ -280,6 +538,55 @@ private function setup_exists($partial) { } } + /** + *@OA\Delete( + * path="/setup/{id}", + * tags={"setup"}, + * summary="Delete setup", + * description="Deletes a setup. Upon success, it returns the ID of the deleted setup.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the setup.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="ID of the deleted setup", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="study_delete", + * ref="#/components/schemas/inline_response_200_14_study_delete", + * ), + * example={ + * "setup_delete": { + * "id": "1" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n401 - Authentication failed. Please provide API key. In order to remove your content, please authenticate.\n402 - Setup does not exists. The setup ID could not be linked to an existing setup.\n404 - Setup deletion failed. Setup is in use by other content (runs, schedules, etc). Can not be deleted.\n405 - Setup deletion failed. Please try again later.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function setup_delete($setup_id) { $setup = $this->Algorithm_setup->getById( $setup_id ); diff --git a/openml_OS/models/api/v1/Api_study.php b/openml_OS/models/api/v1/Api_study.php index 8bb45dfb6..d4edd56c3 100644 --- a/openml_OS/models/api/v1/Api_study.php +++ b/openml_OS/models/api/v1/Api_study.php @@ -21,7 +21,7 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->study_list($segments); return; } - + if (count($segments) == 0) { $this->study_create(); return; @@ -31,19 +31,19 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->status_update($this->input->post('study_id'), $this->input->post('status')); return; } - + if (count($segments) == 1 && is_numeric($segments[0]) && $request_type == 'delete') { $this->study_delete($segments[0]); return; } - + if (count($segments) == 2 && is_numeric($segments[0]) && $segments[1] == 'attach' && $request_type == 'post') { - $this->study_attach_detach($segments[0], true); + $this->study_attach($segments[0]); return; } - + if (count($segments) == 2 && is_numeric($segments[0]) && $segments[1] == 'detach' && $request_type == 'post') { - $this->study_attach_detach($segments[0], false); + $this->study_detach($segments[0]); return; } @@ -52,19 +52,62 @@ function bootstrap($format, $segments, $request_type, $user_id) { if (count($segments) == 2) { $type = $segments[1]; } - - if (is_numeric($segments[0])) { - $this->study_by_id($segments[0], $type); - return; - } else { - $this->study_by_alias($segments[0], $type); - return; - } + $this->study_get($segments[0], $type); + return; } $this->returnError(100, $this->version); } - + + /** + *@OA\Post( + * path="/study", + * tags={"study"}, + * summary="Create new study", + * description="Creates a new study. Upon success, it returns the study id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the study. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.study.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/study).", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the uploaded study", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_study", + * ref="#/components/schemas/inline_response_200_25_upload_study", + * ), + * example={ + * "upload_study": { + * "id": "4328" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n1031 - Description file not present. Please upload the study description.\n1032 - Problem validating uploaded description file. The XML description format does not meet the standards. See the XSD schema.\n1033 - Illegal main entity type. Currently only collections of tasks and can be created.\n1034 - Linked entities are not of the correct type fot this study.\n1035 - Benchmark suites can only be linked to run studies.\n1036 - Referred benchmark suite cannot be found.\n1037 - Referred benchmark suite should be a task collection.\n1038 - Study alias is not unique.\n1039 - Dataset insertion problem. Please contact the administrators.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function study_create() { $xsdFile = xsd('openml.study.upload', $this->controller, $this->version); @@ -206,7 +249,135 @@ private function status_update($study_id, $status) { $this->xmlContents('study-status-update', $this->version, $template_vars); } - + + /** + *@OA\Post( + * path="/study/{id}/attach", + * tags={"study"}, + * summary="Attach a new entity to a study", + * description="Attach a new entity to an exising study. Upon success, it returns the study id, type, and linked entities.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the study. Supplied in the URL path.", + * required=true, + * ), + * @OA\Parameter( + * name="ids", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Comma-separated list of entity IDs to be attached to the study. For instance, if this is a run study, the list of run IDs that need to be added (attached) to the study. Must be supplied as a POST variable.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Properties of the updated study", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="study_attach", + * ref="#/components/schemas/inline_response_200_26_study_attach", + * ), + * example={ + * "study_attach": { + * "id": "1", + * "main_entity_type": "task", + * "linked_entities": "5" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n1041 - Could not find study. Check the study ID in your request.\n1042 - Cannnot attach entities to legacy studies.\n1043 - Please provide POST field 'ids'.\n1044 - Please ensure that the 'ids' in the POST field is a list of natural numbers.\n1045 - Could not attach entities to the study. It appears as if the entity does not exist.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function study_attach($study_id) { + $this->study_attach_detach($study_id, true); + } + + /** + *@OA\Post( + * path="/study/{id}/detach", + * tags={"study"}, + * summary="Detach an entity from a study", + * description="Detach an entity from an exising study. Upon success, it returns the study id, type, and linked entities.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the study.", + * required=true, + * ), + * @OA\Parameter( + * name="ids", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Comma-separated list of entity IDs to be detached from the study. For instance, if this is a run study, the list of run IDs that need to be removed (detached) from the study. Must be supplied as a POST variable.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Properties of the updated study", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_study", + * ref="#/components/schemas/inline_response_200_26_study_attach", + * ), + * example={ + * "study_detach": { + * "id": "1", + * "main_entity_type": "task", + * "linked_entities": "5" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n1041 - Could not find study. Check the study ID in your request.\n1042 - Cannot attach entities to legacy studies.\n1043 - Please provide POST field 'ids'.\n1044 - Please ensure that the 'ids' in the POST field is a list of natural numbers.\n1046 - Could not detach entities from the study. It appears as if the entity does not exist. \n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function study_detach($study_id) { + $this->study_attach_detach($study_id, false); + } + private function study_attach_detach($study_id, $attach) { $study = $this->Study->getById($study_id); if ($study === false) { @@ -275,7 +446,56 @@ private function study_attach_detach($study_id, $attach) { $this->xmlContents('study-attach-detach', $this->version, $template_vars); } - + + /** + *@OA\Delete( + * path="/study/{id}", + * tags={"study"}, + * summary="Delete study", + * description="Deletes a study. Upon success, it returns the ID of the deleted study.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the study.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="ID of the deleted study", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="study_delete", + * ref="#/components/schemas/inline_response_200_24_study_delete", + * ), + * example={ + * "study_delete": { + * "id": "1" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n591 - Please provide API key. In order to remove your content, please authenticate.\n592 - Study does not exists. The study ID could not be linked to an existing study.\n593 - Study deletion failed. Please try again later.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function study_delete($study_id) { $study = $this->Study->getById($study_id); @@ -313,6 +533,61 @@ private function study_delete($study_id) { $this->xmlContents('study-delete', $this->version, array('study' => $study)); } + /** + *@OA\Get( + * path="/study/list/{filters}", + * tags={"study"}, + * summary="List all studies (collections of items)", + * description="List studies, optionally filtered by a range of properties. Any number of properties can be combined by listing them one after the other in the form '/study/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all studies that match the constraints.", + * @OA\Parameter( + * name="filters", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Any combination of these filters + /main_entity_type/{type} - only return studies collecting entities of a given type (e.g. 'task' or 'run'). + /uploader/{ids} - return only evaluations uploaded by specific users, specified as a comma-separated list of user IDs, e.g. ''1,2,3'' + /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, results 11..15 will be returned. Both limit and offset need to be specified. + ", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of studies", + * @OA\JsonContent( + * ref="#/components/schemas/StudyList", + * example={ + * "study_list":{ + * "study":{ + * { + * "id":"1", + * "alias":"Study_1", + * "name":"A large-scale comparison of classification algorithms", + * "creation_date":"2017-07-20 15:51:20", + * "creator":"2" + * }, + * { + * "id":"2", + * "alias":"Study_2", + * "name":"Fast Algorithm Selection using Learning Curves", + * "creation_date":"2017-07-20 15:51:20", + * "creator":"2" + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function study_list($segs) { $legal_filters = array('limit', 'offset', 'main_entity_type', 'uploader', 'status', 'benchmark_suite'); @@ -367,6 +642,59 @@ private function study_list($segs) { $this->xmlContents('study-list', $this->version, array('studies' => $studies)); } + /** + *@OA\Get( + * path="/study/{id}", + * tags={"study"}, + * summary="Get study description by study id or alias", + * description="Returns information about the study with the given id or alias.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="ID or alias of the study.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A study description", + * @OA\JsonContent( + * ref="#/components/schemas/Study", + * example={ + * "study": { + * "id": "99", + * "main_entity_type": "task", + * "name": "CC18 benchmark suite", + * "description": "CC18 benchmark suite", + * "creation_date": "2019-02-16T17:35:58", + * "creator": "1159", + * "data": {"data_id": {"1","2","3"}}, + * "tasks": {"task_id": {"1","2","3"}} + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n601 - Unknown study. The study with the given id or alias was not found in the database\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function study_get($study_id, $type) { + if (is_numeric($study_id)) { + $this->study_by_id($study_id, $type); + return; + } else { + $this->study_by_alias($study_id, $type); + return; + } + } + private function study_by_id($study_id, $entity_type) { $study = $this->Study->getById($study_id); diff --git a/openml_OS/models/api/v1/Api_task.php b/openml_OS/models/api/v1/Api_task.php index 6e23ff0cc..35ca249a0 100644 --- a/openml_OS/models/api/v1/Api_task.php +++ b/openml_OS/models/api/v1/Api_task.php @@ -3,6 +3,9 @@ class Api_task extends MY_Api_Model { protected $version = 'v1'; + const ENTITY_TYPE = "task"; + const ENTITY_SPECIAL_NAME = "task"; + function __construct() { parent::__construct(); @@ -54,12 +57,12 @@ function bootstrap($format, $segments, $request_type, $user_id) { } if (count($segments) == 1 && $segments[0] == 'tag' && $request_type == 'post') { - $this->entity_tag_untag('task', $this->input->post('task_id'), $this->input->post('tag'), false, 'task'); + $this->task_tag($this->input->post('task_id'), $this->input->post('tag')); return; } if (count($segments) == 1 && $segments[0] == 'untag' && $request_type == 'post') { - $this->entity_tag_untag('task', $this->input->post('task_id'), $this->input->post('tag'), true, 'task'); + $this->task_untag($this->input->post('task_id'), $this->input->post('tag')); return; } @@ -71,7 +74,253 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->returnError(100, $this->version); } + /** + *@OA\Post( + * path="/task/tag", + * tags={"task"}, + * summary="Tag a task", + * description="Tags a task.", + * @OA\Parameter( + * name="task_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the task.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="The id of the tagged task", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="task_tag", + * ref="#/components/schemas/inline_response_200_6_task_tag", + * ), + * example={ + * "task_tag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n470 - In order to add a tag, please upload the entity id (either data_id, task_id, flow_id, run_id) and tag (the name of the tag).\n471 - Entity not found. The provided entity_id {data_id, task_id, flow_id, run_id} does not correspond to an existing entity.\n472 - Entity already tagged by this tag. The entity {dataset, task, flow, run} already had this tag.\n473 - Something went wrong inserting the tag. Please contact OpenML Team.\n474 - Internal error tagging the entity. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function task_tag($task_id, $tag) { + $this->entity_tag_untag(self::ENTITY_TYPE, $task_id, $tag, false, self::ENTITY_SPECIAL_NAME); + } + /** + *@OA\Post( + * path="/task/untag", + * tags={"task"}, + * summary="Untag a task", + * description="Untags a task.", + * @OA\Parameter( + * name="task_id", + * in="query", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the task.", + * required=true, + * ), + * @OA\Parameter( + * name="tag", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Tag name", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A the features of the task", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="task_untag", + * ref="#/components/schemas/inline_response_200_7_task_untag", + * ), + * example={ + * "task_untag": { + * "id": "2" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n475 - Please give entity_id {data_id, flow_id, run_id} and tag. In order to remove a tag, please upload the entity id (either data_id, task_id, flow_id, run_id) and tag (the name of the tag).\n476 - Entity {dataset, task, flow, run} not found. The provided entity_id {data_id, task_id, flow_id, run_id} does not correspond to an existing entity.\n477 - Tag not found. The provided tag is not associated with the entity {dataset, task, flow, run}.\n478 - Tag is not owned by you. The entity {dataset, flow, run} was tagged by another user. Hence you cannot delete it.\n479 - Internal error removing the tag. Please contact OpenML Team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ + private function task_untag($task_id, $tag) { + $this->entity_tag_untag(self::ENTITY_TYPE, $task_id, $tag, true, self::ENTITY_SPECIAL_NAME); + } + + /** + *@OA\Get( + * path="/task/list/{filters}", + * tags={"task"}, + * summary="List and filter tasks", + * description="List tasks, possibly filtered by a range of properties from the task itself or from the underlying dataset. Any number of properties can be combined by listing them one after the other in the form '/task/list/{filter}/{value}/{filter}/{value}/...' Returns an array with all tasks that match the constraints.", + * @OA\Parameter( + * name="filters", + * in="path", + * @OA\Schema( + * type="string" + * ), + * description="Any combination of these filters + /limit/{limit}/offset/{offset} - returns only {limit} results starting from result number {offset}. Useful for paginating results. With /limit/5/offset/10, tasks 11..15 will be returned. Both limit and offset need to be specified. + /status/{status} - returns only tasks with a given status, either 'active', 'deactivated', or 'in_preparation'. + /type/{type_id} - returns only tasks with a given task type id. See the list of task types of the ID's (e.g. 1 = Supervised Classification). + /tag/{tag} - returns only tasks tagged with the given tag. + /data_tag/{tag} - returns only tasks for which the underlying dataset is tagged with the given tag. + /{data_quality}/{range} - returns only tasks for which the underlying datasets have certain qualities. {data_quality} can be data_id, data_name, number_instances, number_features, number_classes, number_missing_values. {range} can be a specific value or a range in the form 'low..high'. Multiple qualities can be combined, as in 'number_instances/0..50/number_features/0..10'. + ", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A list of tasks with the given tag", + * @OA\JsonContent( + * ref="#/components/schemas/TaskList", + * example={ + * "task": { + * "task": { + * { + * "task_id":"1", + * "task_type":"Supervised Classification", + * "did":"1", + * "name":"anneal", + * "status":"active", + * "format":"ARFF", + * "input":{ + * { + * "name":"estimation_procedure", + * "value":"1" + * }, + * { + * "name":"evaluation_measures", + * "value":"predictive_accuracy" + * }, + * { + * "name":"source_data", + * "value":"1" + * }, + * { + * "name":"target_feature", + * "value":"class" + * } + * }, + * "quality":{ + * { + * "name":"MajorityClassSize", + * "value":"684" + * }, + * { + * "name":"MaxNominalAttDistinctValues", + * "value":"10.0" + * }, + * { + * "name":"MinorityClassSize", + * "value":"0" + * }, + * { + * "name":"NumBinaryAtts", + * "value":"14.0" + * }, + * { + * "name":"NumberOfClasses", + * "value":"6" + * }, + * { + * "name":"NumberOfFeatures", + * "value":"39" + * }, + * { + * "name":"NumberOfInstances", + * "value":"898" + * }, + * { + * "name":"NumberOfInstancesWithMissingValues", + * "value":"0" + * }, + * { + * "name":"NumberOfMissingValues", + * "value":"0" + * }, + * { + * "name":"NumberOfNumericFeatures", + * "value":"6" + * }, + * { + * "name":"NumberOfSymbolicFeatures", + * "value":"32" + * } + * }, + * "tag":{ + * "basic", + * "study_1", + * "study_7", + * "under100k", + * "under1m" + * } + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n480 - Illegal filter specified.\n481 - Filter values/ranges not properly specified.\n482 - No results. There where no matches for the given constraints.\n483 - Can not specify an offset without a limit.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function task_list($segs, $user_id) { $legal_filters = array('type', 'tag', 'data_tag', 'status', 'limit', 'offset', 'task_id', 'data_id', 'data_name', 'number_instances', 'number_features', 'number_classes', 'number_missing_values'); @@ -149,7 +398,116 @@ private function task_list($segs, $user_id) { $this->xmlContents( 'tasks', $this->version, array( 'tasks' => $tasks_res ) ); } - + /** + *@OA\Get( + * path="/task/{id}", + * tags={"task"}, + * summary="Get task description", + * description="Returns information about a task. The information includes the task type, input data, train/test sets, and more.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="ID of the task.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A task description", + * @OA\JsonContent( + * ref="#/components/schemas/Task", + * example={ + * "task": { + * "task_id":"1", + * "task_type":"Supervised Classification", + * "input":{ + * { + * "name":"source_data", + * "data_set":{ + * "data_set_id":"1", + * "target_feature":"class" + * } + * }, + * { + * "name":"estimation_procedure", + * "estimation_procedure":{ + * "type":"crossvalidation", + * "data_splits_url":"https://www.openml.org/api_splits/get/1/Task_1_splits.arff", + * "parameter":{ + * { + * "name":"number_repeats", + * "value":"1" + * }, + * { + * "name":"number_folds", + * "value":"10" + * }, + * { + * "name":"percentage" + * }, + * { + * "name":"stratified_sampling", + * "value":"true" + * } + * } + * } + * }, + * { + * "name":"cost_matrix", + * "cost_matrix":{} + * }, + * { + * "name":"evaluation_measures", + * "evaluation_measures": + * { + * "evaluation_measure":"predictive_accuracy" + * } + * } + * }, + * "output":{ + * "name":"predictions", + * "predictions":{ + * "format":"ARFF", + * "feature":{ + * { + * "name":"repeat", + * "type":"integer" + * }, + * { + * "name":"fold", + * "type":"integer" + * }, + * { + * "name":"row_id", + * "type":"integer" + * }, + * { + * "name":"confidence.classname", + * "type":"numeric" + * }, + * { + * "name":"prediction", + * "type":"string" + * } + * } + * } + * }, + * "tag":{"basic","study_1","under100k","under1m"} + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n150 - Please provide task_id.\n151 - Unknown task. The task with the given id was not found in the database\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function task($task_id) { $task = $this->Task->getById($task_id); if($task === false) { @@ -197,6 +555,55 @@ private function task_inputs($task_id) { $this->xmlContents('task-inputs', $this->version, array('task' => $task, 'inputs' => $inputs)); } + /** + *@OA\Delete( + * path="/task/{id}", + * tags={"task"}, + * summary="Delete task", + * description="Deletes a task. Upon success, it returns the ID of the deleted task.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="Id of the task.", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="ID of the deleted task", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="task_delete", + * ref="#/components/schemas/inline_response_200_4_task_delete", + * ), + * example={ + * "task_delete": { + * "id": "4328" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n450 - Please provide API key. In order to remove your content, please authenticate.\n451 - Authentication failed. The API key was not valid. Please try to login again, or contact api administrators.\n452 - Task does not exists. The task ID could not be linked to an existing task.\n454 - Task is executed in some runs. Delete these first.\n455 - Deleting the task failed. Please contact support team.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ private function task_delete($task_id) { $task = $this->Task->getById($task_id); @@ -243,6 +650,55 @@ private function task_delete($task_id) { $this->xmlContents( 'task-delete', $this->version, array( 'task' => $task ) ); } + /** + *@OA\Post( + * path="/task", + * tags={"task"}, + * summary="Upload task", + * description="Uploads a task. Upon success, it returns the task id.", + * @OA\Parameter( + * name="description", + * in="query", + * @OA\Schema( + * type="file" + * ), + * description="An XML file describing the task. Only name, description, and task format are required. Also see the [XSD schema](https://www.openml.org/api/v1/xsd/openml.task.upload) and an [XML example](https://www.openml.org/api/v1/xml_example/task).", + * required=true, + * ), + * @OA\Parameter( + * name="api_key", + * in="query", + * @OA\Schema( + * type="string" + * ), + * description="Api key to authenticate the user", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="Id of the uploaded task", + * @OA\JsonContent( + * type="object", + * @OA\Property( + * property="upload_task", + * ref="#/components/schemas/inline_response_200_5_upload_task", + * ), + * example={ + * "upload_task": { + * "id": "4328" + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n530 - Description file not present. Please upload the task description.\n531 - Internal error. Please contact api support team\n532 - Problem validating uploaded description file. The XML description format does not meet the standards\n533 - Task already exists.\n534 - Error creating the task.\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ public function task_upload() { $description = isset( $_FILES['description'] ) ? $_FILES['description'] : false; diff --git a/openml_OS/models/api/v1/Api_tasktype.php b/openml_OS/models/api/v1/Api_tasktype.php index f95a9130d..2f6552a46 100644 --- a/openml_OS/models/api/v1/Api_tasktype.php +++ b/openml_OS/models/api/v1/Api_tasktype.php @@ -16,11 +16,139 @@ function bootstrap($format, $segments, $request_type, $user_id) { $getpost = array('get','post'); + /** + *@OA\Get( + * path="/tasktype/list", + * tags={"tasktype"}, + * summary="List all task types", + * description="Returns an array with all task types in the system.", + * @OA\Response( + * response="default", + * description="Unexpected error", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + * @OA\Response( + * response=200, + * description="A task description", + * @OA\JsonContent( + * ref="#/components/schemas/TaskTypeList", + * example={ + * "task_types":{ + * "task_type":{ + * { + * "id":"1", + * "name":"Supervised Classification", + * "description":"In supervised classification, you are given ...", + * "creator":"Joaquin Vanschoren, Jan van Rijn, Luis Torgo, Bernd Bischl" + * }, + * { + * "id":"2", + * "name":"Supervised Regression", + * "description":"Given a dataset with a numeric target ...", + * "creator":"Joaquin Vanschoren, Jan van Rijn, Luis Torgo, Bernd Bischl" + * } + * } + * } + * } + * ), + * ), + *) + */ if (count($segments) == 1 && $segments[0] == 'list') { $this->tasktype_list(); return; } + /** + *@OA\Get( + * path="/tasktype/{id}", + * tags={"tasktype"}, + * summary="Get task type description", + * description="Returns information about a task type. The information includes a description, the given inputs and the expected outputs.", + * @OA\Parameter( + * name="id", + * in="path", + * @OA\Schema( + * type="integer" + * ), + * description="ID of the task.", + * required=true, + * ), + * @OA\Response( + * response=200, + * description="A task type description", + * @OA\JsonContent( + * ref="#/components/schemas/TaskType", + * example={ + * "task_type": { + * "id": "1", + * "name": "Supervised Classification", + * "description": "In supervised classification, you are given an input dataset in which instances are labeled with a certain class. The goal is to build a model that predicts the class for future unlabeled instances. The model is evaluated using a train-test procedure, e.g. cross-validation.

\ + * \ + * To make results by different users comparable, you are given the exact train-test folds to be used, and you need to return at least the predictions generated by your model for each of the test instances. OpenML will use these predictions to calculate a range of evaluation measures on the server.

\ + * \ + * You can also upload your own evaluation measures, provided that the code for doing so is available from the implementation used. For extremely large datasets, it may be infeasible to upload all predictions. In those cases, you need to compute and provide the evaluations yourself.

\ + * \ + * Optionally, you can upload the model trained on all the input data. There is no restriction on the file format, but please use a well-known format or PMML.", + * "creator": { + * "Joaquin Vanschoren", + * "Jan van Rijn", + * "Luis Torgo", + * "Bernd Bischl" + * }, + * "contributor": { + * "Bo Gao", + * "Simon Fischer", + * "Venkatesh Umaashankar", + * "Michael Berthold", + * "Bernd Wiswedel", + * "Patrick Winter" + * }, + * "creation_date": "2013-01-24 00:00:00", + * "input": { + * { + * "name": "source_data", + * "requirement": "required", + * "data_type": "numeric" + * }, + * { + * "name": "target_feature", + * "requirement": "required", + * "data_type": "string" + * }, + * { + * "name": "estimation_procedure", + * "requirement": "required", + * "data_type": "numeric" + * }, + * { + * "name": "cost_matrix", + * "data_type": "json" + * }, + * { + * "name": "custom_testset", + * "data_type": "json" + * }, + * { + * "name": "evaluation_measures", + * "data_type": "string" + * } + * } + * } + * } + * ), + * ), + * @OA\Response( + * response=412, + * description="Precondition failed. An error code and message are returned.\n240 - Please provide task type ID.\n241 - Unknown task type. The task type with the given id was not found in the database\n", + * @OA\JsonContent( + * ref="#/components/schemas/Error", + * ), + * ), + *) + */ if (count($segments) == 1 && is_numeric($segments[0]) && in_array($request_type, $getpost)) { $this->tasktype($segments[0]); return; diff --git a/openml_OS/models/api/v1/Api_user.php b/openml_OS/models/api/v1/Api_user.php index 14a988483..71b946bab 100644 --- a/openml_OS/models/api/v1/Api_user.php +++ b/openml_OS/models/api/v1/Api_user.php @@ -17,12 +17,13 @@ function bootstrap($format, $segments, $request_type, $user_id) { $this->outputFormat = $format; # http://test.openml.org/api/v1/user/list/uploader/1,2 + if (count($segments) >= 1 && $segments[0] == 'list') { array_shift($segments); $this->username_list($segments); return; } - + /*$getpost = array('get','post'); if (count($segments) == 1 && is_numeric($segments[0]) && $request_type == 'delete') { @@ -82,6 +83,35 @@ function bootstrap($format, $segments, $request_type, $user_id) { } */ + /** + *@OA\Get( + * path="/user/list", + * tags={"user"}, + * summary="List all users by user id", + * description="Returns an array with all user ids and names.", + * @OA\Response( + * response=200, + * description="A list of users", + * @OA\JsonContent( + * ref="#/components/schemas/UserList", + * example={ + * "users":{ + * "user":{ + * { + * "id":"1", + * "username":"janvanrijn@gmail.com" + * }, + * { + * "id":"2", + * "username":"joaquin.vanschoren@gmail.com" + * } + * } + * } + * } + * ) + * ) + *) + */ private function username_list($segs) { # pass uploader list to get username list $legal_filters = array('user_id');