{
"openapi": "3.0.1",
"info": {
"title": "Catalogues REST",
"description": "Catalogues (Harmonized controlled terminology) are a key element in the process of data validation and reporting. A harmonized terminology is used to collect and analyse data in a coherent way with the aim to support scientific research.\n\nThis API allows to retrieve the catalogues published on Data Collection Framework.",
"version": "1.0"
},
"servers": [
{
"url": "https://openscaie-dev.azure-api.net/api/catalogues"
}
],
"paths": {
"/catalogue-file": {
"post": {
"summary": "CatalogueFile",
"description": "Export functionalities are supported by the method ExportCatalogueFile which differentiates the operation through the exportType parameter. In case that parameter is not provided or mistyped then the web service replies with the fault message: Operation not supported \r\n\r\nExport catalogue\r\n\r\nIn order to export a catalogue the ExportCatalogueFile method must be invoked passing as parameters the catalogueCode and specifying “catalogFullDefinition” in the exportType parameter.\r\nThe catalogueVersion is optional and can only contain a published version (even if deprecated). The default - if not provided – is the last published version. Please note that in this case the fileType “XML” must be passed.\r\nThe web service replies with a message containing in attachment the xml export file.\r\nIn case the catalogue is not published the web service replies with the following fault: Fault occurred while processing.\r\nIn case a non-existing version is passed, the web service replies with the following fault: Catalogue version does not exist.\r\nIn case the passed version does not have the proper format (e.g. 1.0 major or 1.1 minor), the web service replies with the following fault: Version format not correct.\r\n\r\nExport the release note for a catalogue\r\n\r\nIn order to export the release note of a catalogue version, the ExportCatalogueFile method must be invoked passing as parameters the catalogueCode and specifying “releaseNote” in the exportType parameter. The catalogueVersion is optional and if it is not provided the last published version is considered. Please note that in this case the fileType “XML” must be passed.\r\nThe web service replies with a message containing in attachment the zipped export file.\r\nIf the catalogue has never been published and the catalogueVersion is not provided then the web service replies with the following fault: Fault occurred while processing.\r\nIf the catalogue has been published and the catalogueVersion is provided in the right format (X.Y) then the web service checks whether the version exists. If not, it replies with the following fault: Catalogue version does not exist.\r\nIf the catalogue has been published and the catalogueVersion is provided in the wrong format (X.Y.Z) then the web service replies with the following fault: Version format not correct.\r\n\r\n\r\nExport a hierarchy\r\n\r\nIn order to export a hierarchy, even if deprecated, the ExportCatalogueFile method must be invoked passing as parameters the catalogueCode and specifying “hierarchyDefinition” in the exportType parameter. \r\nThe catalogue must be published and the catalogueCode parameter must be passed in the format catalogCode.hierarchyCode. If the hierarchyCode is missing the master hierarchy is considered. \r\nThe catalogueVersion is optional and if it is not provided the last published catalogue version is considered. Please note that the fileType “XML” must be passed.\r\nThe web service replies with a message containing in attachment the xml export file.\r\nIf the catalogue is not published the web service replies with the following fault: Fault occurred while processing.\r\nIf the catalogue has been published but the hierarchy has been added after the publication, then the web service replies with the a fault similar to the following one: CM_CATc_T02C194_CATHIERCODE_T02C194e_1_0.xml does not exist.\r\nIf the catalogue has been published and the catalogueVersion is provided in the right format (X.Y) then the web service checks whether the version exists. If not it replies with the following fault: Catalogue version does not exist.\r\nIf the catalogue has been published and the catalogueVersion is provided in the wrong format (X.Y.Z) then the web service replies with the following fault: version format not correct.\r\n\r\n\r\nExport a group\r\n\r\nIn order to export a group of hierarchies the ExportCatalogueFile method must be invoked passing as parameters the group code and specifying “group” in the exportType parameter. Please note that the fileType “XML” must be passed. The other parameters are ignored.\r\nThe web service replies with a message containing in attachment the zip file of the exported hierarchies.\r\nPlease remember that a hierarchy, even if deprecated, is exported only if it is included in a published or deprecated catalogue. If the master hierarchy is included, then any other hierarchies assigned to the group are omitted. \r\nIf the provided group does not exist, the web service replies with the following fault: group does not exist.",
"operationId": "5aafa415c0c61299adefd1f4",
"requestBody": {
"content": {
"application/json": {
"example": {
"ExportCatalogueFile": {
"catalogueCode": "GENDER",
"catalogueVersion": "2024-02-04",
"exportType": "catalogFullDefinition",
"group": "",
"dcCode": "",
"fileType": "XML"
}
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"ExportCatalogueFileResponse": {
"return": {
"filename": "GENDER_FULL_2_4.xml",
"isZipped": "false",
"filetype": "XML"
}
}
}
}
}
}
}
}
},
"/catalogue-group-list": {
"post": {
"summary": "CatalogueGroupList",
"description": "This operation allows downloading the list of catalogue groups defined in the system. The operation does not have any input parameters.\r\nThe web service replies with a message containing the list of Groups in XML format.",
"operationId": "5aaf82b5a4972b4859afa52f",
"requestBody": {
"content": {
"application/json": {
"example": {
"getCatalogueGroupList": ""
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"getCatalogueGroupListResponse": {
"return": "SSD2sampling methodsMTXFACETSGeographical distributionEcological parameters"
}
}
}
}
}
}
}
},
"/catalogue-list": {
"post": {
"summary": "CatalogueList",
"description": "This operation allows downloading the list of catalogues, possibly restricted to a certain catalogue group or data collection.\r\n\r\n\r\n\r\nDownload catalogues for a data collection\r\n\r\nTo obtain the catalogues related to a data collection the getCatalogueList method must be invoked passing as parameter (arg1) the data collection code and setting the output type (arg2) as XML. \r\nThe web service replies with a message containing the list of catalogues in XML format.\r\nIf the data Collection does not exist then operation reply with the following soap message: Invalid data collection code.\r\n\r\n\r\n\r\nDownload catalogues in a group\r\n\r\nTo obtain the catalogues in a group the getCatalogueList method must be invoked passing as parameter (arg0) the catalogue group code and the format of the output (arg2) as XML.\r\nThe web service replies with a message containing the list of catalogues in XML format.",
"operationId": "5aaf8e96cff4777e04bcd83b",
"requestBody": {
"content": {
"application/json": {
"example": {
"getCatalogueList": {
"arg0": "Geographical distribution",
"arg1": "",
"arg2": "XML"
}
}
}
}
},
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"example": {
"getCatalogueListResponse": {
"return": "COORDPRECOORDPRECatalogue which contains precision of coordinates (longitude and latitude) used for geographical distribution data collections in conjunction with global regions cataloguetruefalse1.12017-10-31T15:28:55.274+01:00PUBLISHED MINORECOLPARAMECOLPARAMCatalogue which contains ecological parameterstruefalse2.02018-01-30T09:07:38.253+01:00PUBLISHED MAJOR"
}
}
}
}
}
}
}
}
},
"components": {
"securitySchemes": {
"apiKeyHeader": {
"type": "apiKey",
"name": "Ocp-Apim-Subscription-Key",
"in": "header"
},
"apiKeyQuery": {
"type": "apiKey",
"name": "subscription-key",
"in": "query"
}
}
},
"security": [
{
"apiKeyHeader": [ ]
},
{
"apiKeyQuery": [ ]
}
]
}