design.json

{
    "swagger": "2.0",
    "info": {
        "description": "This is ongoing work for the MK:Smart Data Hub API.  You can find out more about MK:Smart at [http://mksmart.org](http://mksmart.org)",
        "version": "1.0.0",
        "title": "MK Data Hub API",
        "termsOfService": "http://datahub.mksmart.org",
        "contact": {
            "email": "enrico.daga@open.ac.uk"
        },
        "license": {
            "name": "Apache 2.0",
            "url": "http://www.apache.org/licenses/LICENSE-2.0.html"
        }
    },
    "host": "datahub.mksmart.org",
    "basePath": "/api/1.0",
    "tags": [
        {
            "name": "Data Catalogue",
            "description": "All about datasets, categories and licenses",
            "externalDocs": {
                "description": "List the datasets a user can view. Access dataset metadata.",
                "url": "#"
            }
        },
        {
            "name": "Find Data",
            "description": "About finding data in the datahub",
            "externalDocs": {
                "description": "More about finding data",
                "url": "#"
            }
        },
        {
            "name": "Provide Data",
            "description": "About pushing data in the datahub",
            "externalDocs": {
                "description": "More about providing data",
                "url": "#"
            }
        }
    ],
    "schemes": [
        "https"
    ],
    "paths": {
        "/datasets": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Find Data"
                ],
                "summary": "List datasets",
                "description": "List the datasets",
                "operationId": "catalogueListDatasets",
                "consumes": [
                    "*/*"
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "in": "query",
                        "type": "string",
                        "name": "fields",
                        "default": "id,title,url"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Returns the list of datasets",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/DatasetItem"
                            }
                        }
                    },
                    "405": {
                        "description": "Invalid input",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset": {
            "put": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Creates a dataset in the catalogue.",
                "description": "Add a new dataset in the data catalogue. <p>A dataset may have one of two type of sources (the _source_ field): temporal and entities. <p>_Temporal_ data is meant to be populated pushing data streams to a feed API using the EEML format. Once created, a new feed API exposed to allow you to push the data. <p>_Entities_ data is populated uploading files or pointing to open web resources providing an HTTP urls. Files must be in CSV format. Multiples files and URLs are allowed for this type of dataset. <p>A dataset supports one of these two type of sources: _temporal_ or _entities_, but not both of them. <p>You need to provide an __api key__. If you haven't done already, you can activate a key to the Data Catalogue dataset through the MK Data Hub Portal. Go to _Find Data_ and look for the _Data Catalogue_ dataset. Then, use the _activate_ button to register a key. That key can be used to read and write to the Data Catalogue dataset through this API.",
                "operationId": "updateDatasetWithForm",
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "dataset",
                        "in": "body",
                        "description": "Dataset",
                        "required": true,
                        "schema": {
                            "enum": [
                                {
                                    "$ref": "#/definitions/DatasetCreateTypeTemporal"
                                },
                                {
                                    "$ref": "#/definitions/DatasetCreateTypeEntities"
                                }
                            ]
                        }
                    }
                ],
                "responses": {
                    "201": {
                        "description": "Dataset created",
                        "headers": {
                            "Location": {
                                "description": "API location of the dataset metadata",
                                "type": "string"
                            }
                        },
                        "schema": {
                            "$ref": "#/definitions/DatasetItem"
                        }
                    },
                    "403": {
                        "description": "Forbidden. Api key cannot create Datasets",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "406": {
                        "description": "The dataset already exists, to modify the data use the sections endpoints: /info, /access and /stream /",
                        "schema": {
                            "$ref": "/#definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{id}": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Find Data",
                    "Provide Data"
                ],
                "summary": "Find dataset by ID",
                "description": "Access a dataset metadata.",
                "operationId": "getDatasetById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/Dataset"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Delete a dataset",
                "description": "",
                "operationId": "deleteDataset",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "api_key",
                        "in": "header",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "id",
                        "in": "path",
                        "description": "Dataset id to delete",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Dataset deleted",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid dataset value",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{id}/info": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Get dataset information",
                "description": "Returns a single dataset",
                "operationId": "getDatasetInfoById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/DatasetInfo"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Replace dataset info",
                "description": "",
                "operationId": "putDatasetInfoById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "access",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/DatasetInfo"
                        },
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid input data",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Modify dataset info (Patching)",
                "description": "With this method, only the provided fields are updated. The remaining fields are not modified.",
                "operationId": "patchDatasetInfoById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "access",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/DatasetInfo"
                        },
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid input data",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{id}/feed": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Get Feed information",
                "description": "Returns the feed section of a dataset metadata",
                "operationId": "getDatasetStreamById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/DatasetFeed"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Replace stream information",
                "description": "",
                "operationId": "putDatasetStreamById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "access",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/DatasetFeed"
                        },
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid input data",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Modify stream information",
                "description": "With this method, only the provided fields are updated. The remaining fields are not modified.",
                "operationId": "patchDatasetStreamById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "access",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/DatasetFeed"
                        },
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid input data",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{datasetId}/file/{fileId}": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "operationId": "getFileMetadata",
                "description": "Retrieve file metadata",
                "summary": "Retrieve file metadat",
                "parameters": [
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "fileId",
                        "in": "path",
                        "description": "ID of the file",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The file",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "File not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "delete": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Delete a dataset",
                "description": "",
                "operationId": "deleteFile",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "api_key",
                        "in": "header",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "Dataset id",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "fileId",
                        "in": "path",
                        "description": "File id to be deleted",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "204": {
                        "description": "Dataset deleted",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid dataset value",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "description": "Update file metadata",
                "summary": "Update file metadata",
                "operationId": "updateFileMetadata",
                "parameters": [
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "fileId",
                        "in": "path",
                        "required": true,
                        "description": "ID of the file",
                        "type": "string"
                    },
                    {
                        "name": "metadata",
                        "in": "body",
                        "required": true,
                        "description": "JSON file",
                        "schema": {
                            "enum": [
                                {
                                    "$ref": "#/definitions/UploadedSource"
                                },
                                {
                                    "$ref": "#/definitions/HttpSource"
                                }
                            ]
                        }
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "The file metadata has been updated",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "File not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{datasetId}/http/": {
            "put": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Registers a new HTTP file data source",
                "operationId": "registerHttpSource",
                "parameters": [
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "metadata",
                        "in": "body",
                        "required": true,
                        "description": "JSON file",
                        "schema": {
                            "$ref": "#/definitions/HttpSource"
                        }
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "The HTTP source has been registered",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid request",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{datasetId}/http/{fileId}": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "View the last fetched version of the file",
                "operationId": "getHttpSource",
                "parameters": [
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "fileId",
                        "in": "path",
                        "description": "ID of the HTTP data source",
                        "required": true,
                        "type": "string"
                    }
                ],
                "produces": [
                    "text/csv"
                ],
                "responses": {
                    "200": {
                        "description": "Returns the file",
                        "schema": {
                            "type": "file"
                        }
                    },
                    "400": {
                        "description": "Invalid request",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{datasetId}/uploads/": {
            "post": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Creates a new file data source (upload)",
                "description": "Uploads a source file for the dataset. The dataset MUST be of type __file__",
                "operationId": "uploadFile",
                "consumes": [
                    "multipart/form-data"
                ],
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "title",
                        "in": "formData",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "file",
                        "in": "formData",
                        "required": true,
                        "type": "file"
                    },
                    {
                        "name": "mimeType",
                        "in": "formData",
                        "required": true,
                        "type": "string",
                        "enum": [
                            "text/csv"
                        ]
                    }
                ],
                "responses": {
                    "201": {
                        "description": "file uploaded succesfully",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid input data",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden.",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{datasetId}/uploads/{fileId}": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "description": "Retrieve the uploaded file.",
                "summary": "Retrieve file",
                "operationId": "getFile",
                "parameters": [
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "fileId",
                        "in": "path",
                        "description": "ID of the file",
                        "required": true,
                        "type": "string"
                    }
                ],
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "The file metadata",
                        "schema": {
                            "$ref": "#/definitions/UploadedSource"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "File not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Data Catalogue"
                ],
                "description": "Update file",
                "operationId": "putFile",
                "summary": "Update file",
                "parameters": [
                    {
                        "name": "datasetId",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "fileId",
                        "in": "path",
                        "required": true,
                        "description": "ID of the file",
                        "type": "string"
                    }
                ],
                "consumes": [
                    "application/json"
                ],
                "produces": [
                    "application/json"
                ],
                "responses": {
                    "200": {
                        "description": "The file metadata has been updated",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "File not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/dataset/{id}/access": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "View access policies of dataset",
                "description": "",
                "operationId": "getDatasetAccessById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/Access"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "put": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Replace access policies of dataset",
                "description": "",
                "operationId": "putDatasetAccessById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset to return",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "access",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/Access"
                        },
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/Access"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "406": {
                        "description": "Conflict. Access policies are inconsistent.",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            },
            "patch": {
                "tags": [
                    "Data Catalogue",
                    "Provide Data"
                ],
                "summary": "Modify access policies of dataset",
                "description": "With this method, only the provided fields are updated. The remaining fields are not modified.",
                "operationId": "patchDatasetAccessById",
                "produces": [
                    "application/json"
                ],
                "parameters": [
                    {
                        "name": "id",
                        "in": "path",
                        "description": "ID of dataset",
                        "required": true,
                        "type": "string"
                    },
                    {
                        "name": "access",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/Access"
                        },
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "$ref": "#/definitions/Access"
                        }
                    },
                    "400": {
                        "description": "Invalid ID supplied",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "404": {
                        "description": "Dataset not found",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "406": {
                        "description": "Conflict. Access policies are inconsistent.",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/categories": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Find Data"
                ],
                "responses": {
                    "200": {
                        "description": "Licenses",
                        "schema": {
                            "type": "array",
                            "items": {
                                "category": {
                                    "type": "string"
                                },
                                "datasets": {
                                    "type": "integer"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/categories/{category}": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Find Data"
                ],
                "parameters": {
                    "category": {
                        "in": "path",
                        "type": "string",
                        "required": true
                    }
                },
                "responses": {
                    "200": {
                        "description": "Datasets in category",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/DatasetItem"
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/licenses": {
            "get": {
                "tags": [
                    "Data Catalogue",
                    "Find Data"
                ],
                "responses": {
                    "200": {
                        "description": "Licenses",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/License"
                            }
                        }
                    },
                    "403": {
                        "description": "Forbidden",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    },
                    "500": {
                        "description": "Server Error (unexpected)",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/datasources": {
            "get": {
                "tags": [
                    "Provide Data"
                ],
                "summary": "List my data sources",
                "description": "Provides a list of the data sources.",
                "operationId": "datasourcesList",
                "produces": [
                    "application/json"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/Datasource"
                            }
                        }
                    },
                    "500": {
                        "description": "Server Error",
                        "schema": {
                            "$ref": "#/definitions/ApiResponse"
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        },
        "/subscriptions": {
            "get": {
                "tags": [
                    "Find Data"
                ],
                "summary": "List my subscriptions",
                "description": "Provides a list of the subscriptions.",
                "operationId": "subscriptionsList",
                "produces": [
                    "application/json"
                ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "successful operation",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/Subscription"
                            }
                        }
                    }
                },
                "security": [
                    {
                        "key": []
                    }
                ]
            }
        }
    },
    "securityDefinitions": {
        "key": {
            "type": "apiKey",
            "name": "key",
            "in": "header"
        }
    },
    "definitions": {
        "DatasetInfo": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string",
                    "description": "The name of the dataset"
                },
                "categories": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": [
                            "business",
                            "crime",
                            "demography",
                            "education",
                            "employment",
                            "energy",
                            "environment",
                            "geo",
                            "health",
                            "housing",
                            "location",
                            "media",
                            "public sector",
                            "sensor",
                            "social media",
                            "statistics",
                            "transport",
                            "water"
                        ]
                    },
                    "minItems": 1,
                    "uniqueItems": true
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    },
                    "uniqueItems": true
                },
                "formats": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "ownership": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "sourceWebsite": {
                    "type": "string"
                },
                "sourceName": {
                    "type": "string"
                },
                "pricePlan": {
                    "type": "string",
                    "enum": [
                        "Free"
                    ]
                },
                "licenses": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": [
                            "flickr-apis-terms-of-use",
                            "terms-and-conditions-for-information-and-services-at-food-gov-ukratings",
                            "odc-database-contents-license-dbcl-1-0",
                            "netatmo-api-terms-of-use",
                            "other",
                            "open-database-license-odbl-v1-0",
                            "os-open-data-license",
                            "creative-commons-attribution-license",
                            "open-government-license"
                        ]
                    },
                    "minItems": 1
                },
                "statement": {
                    "type": "string"
                }
            }
        },
        "DatasetFeed": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "description": "Stream datatype",
                    "enum": [
                        "Sensor",
                        "Event"
                    ]
                },
                "id": {
                    "type": "string",
                    "description": "The Feed id",
                    "readOnly": true
                },
                "previewUrl": {
                    "type": "string",
                    "description": "Link to the preview feed page in the data hub portal"
                },
                "feedUrl": {
                    "type": "string",
                    "description": "Feed API url to be used to write/read streams."
                },
                "key": {
                    "type": "string",
                    "description": "Key (label) used to write to the stream API. If the key name does not match an existing API key, a new one is created and bound to the given label."
                },
                "location": {
                    "type": "string",
                    "description": "Stream location mode.",
                    "enum": [
                        "Fixed",
                        "Mobile"
                    ]
                },
                "latitute": {
                    "type": "string",
                    "format": "float",
                    "description": "Source location latitude.",
                    "maximum": 90,
                    "minimum": -90
                },
                "longitude": {
                    "type": "string",
                    "format": "float",
                    "description": "Source location longitude.",
                    "maximum": 180,
                    "minimum": -180
                },
                "elevation": {
                    "type": "integer",
                    "format": "int32",
                    "description": "Source location elevation."
                },
                "postcode": {
                    "type": "string",
                    "description": "Postcode"
                },
                "streams": {
                    "type": "array",
                    "minItems": 1,
                    "items": {
                        "$ref": "#/definitions/Stream"
                    }
                }
            }
        },
        "UploadedSource": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "readOnly": true
                },
                "name": {
                    "type": "string",
                    "description": "Name of the file"
                }
            }
        },
        "HttpSource": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "readOnly": true
                },
                "name": {
                    "type": "string",
                    "description": "Name of the file"
                },
                "url": {
                    "type": "string",
                    "description": "HTTP location of the file"
                },
                "updateRate": {
                    "type": "string",
                    "description": "Update rate",
                    "enum": [
                        "hour",
                        "daily",
                        "weekly",
                        "notify"
                    ],
                    "default": "notify"
                }
            }
        },
        "Stream": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Stream ID"
                },
                "title": {
                    "type": "string",
                    "description": "Stream title"
                },
                "unitType": {
                    "type": "string",
                    "description": "Stream Unit Type",
                    "enum": [
                        "Basic SI",
                        "Derived SI",
                        "Conversion Based Units",
                        "Derived Units",
                        "Context Dependend Units"
                    ]
                },
                "unitName": {
                    "type": "string",
                    "description": "Stream Unit Name"
                },
                "unitSymbol": {
                    "type": "string",
                    "description": "Stream Unit Symbol"
                },
                "maximum": {
                    "type": "string",
                    "description": "Stream maximum value"
                },
                "minimum": {
                    "type": "string",
                    "description": "Stream minimum value"
                }
            }
        },
        "Access": {
            "type": "object",
            "properties": {
                "provider": {
                    "type": "string"
                },
                "everyone": {
                    "$ref": "#/definitions/AccessPolicy"
                },
                "exceptions": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/AccessPolicyException"
                    }
                }
            }
        },
        "AccessPolicy": {
            "type": "object",
            "properties": {
                "view": {
                    "type": "boolean",
                    "default": false
                },
                "subscribe": {
                    "type": "boolean",
                    "default": false
                }
            }
        },
        "AccessPolicyException": {
            "type": "object",
            "properties": {
                "user": {
                    "type": "string"
                },
                "view": {
                    "type": "boolean",
                    "default": false
                },
                "subscribe": {
                    "type": "boolean",
                    "default": false
                }
            },
            "required": [
                "user"
            ]
        },
        "DatasetMeta": 
		{
			"type": "object",
			"properties": 
			{
				"id": 
				{
					"type": "string",
					"description": "Dataset UUID",
					"readOnly": true
				},

				"type": 
				{
					"type": "string",
					"description": "The type of dataset",
					"enum": 
					[
						"temporal",
						"entities"
					],

					"readOnly": true
				},

				"lastModified": 
				{
					"type": "string",
					"format": "date-time",
					"readOnly": true
				},

				"created": 
				{
					"type": "string",
					"format": "date-time",
					"readOnly": true
				},

				"pageUrl": 
				{
					"type": "string",
					"description": "The web page of the dataset",
					"readOnly": true
				},

				"apiUrl": 
				{
					"type": "string",
					"description": "The url to the dataset json description",
					"readOnly": true
				}
			}
		},
		"DatasetItem": 
		{
			"allOf": 
			[
				{
					"$ref": "#/definitions/DatasetInfo"
				},

				{
					"$ref": "#/definitions/DatasetMeta"
				}
			]
		},
        "Dataset": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "description": "Dataset UUID"
                },
                "type": {
                    "type": "string",
                    "description": "The type of data source",
                    "enum": [
                        "temporal",
                        "entities"
                    ]
                },
                "lastModified": {
                    "type": "string",
                    "format": "date-time",
                    "readOnly": true
                },
                "created": {
                    "type": "string",
                    "format": "date-time",
                    "readOnly": true
                },
                "pageUrl": {
                    "type": "string",
                    "description": "The web page of the dataset",
                    "readOnly": true
                },
                "apiUrl": {
                    "type": "string",
                    "description": "The url to the dataset json description",
                    "readOnly": true
                },
                "info": {
                    "type": "object",
                    "$ref": "#/definitions/DatasetInfo"
                },
                "feed": {
                    "type": "object",
                    "$ref": "#/definitions/DatasetFeed"
                },
                "access": {
                    "type": "object",
                    "$ref": "#/definitions/Access"
                }
            },
            "required": [
                "id"
            ]
        },
        "DatasetCreateTypeTemporal": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "description": "The type of data source. MUST be 'temporal'",
                    "enum": [
                        "temporal"
                    ]
                },
                "info": {
                    "type": "object",
                    "$ref": "#/definitions/DatasetInfo"
                },
                "feed": {
                    "type": "object",
                    "$ref": "#/definitions/DatasetFeed"
                },
                "access": {
                    "type": "object",
                    "$ref": "#/definitions/Access"
                }
            },
            "required": [
                "type",
                "info",
                "feed"
            ]
        },
        "DatasetCreateTypeEntities": {
            "type": "object",
            "properties": {
                "type": {
                    "type": "string",
                    "description": "The type of data source. MUST be 'entities'",
                    "enum": [
                        "entities"
                    ]
                },
                "info": {
                    "type": "object",
                    "$ref": "#/definitions/DatasetInfo"
                },
                "access": {
                    "type": "object",
                    "$ref": "#/definitions/Access"
                }
            },
            "required": [
                "type",
                "info"
            ]
        },
        "License": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "readOnly": true
                },
                "title": {
                    "type": "string"
                },
                "description": {
                    "type": "string"
                },
                "pageUrl": {
                    "type": "string",
                    "readOnly": true
                },
                "apiUrl": {
                    "type": "string",
                    "readOnly": true
                },
                "permissions": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": [
                            "distribute",
                            "modify",
                            "display"
                        ]
                    }
                },
                "prohibitions": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": [
                            "distribute",
                            "modify",
                            "display"
                        ]
                    }
                },
                "duties": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "enum": [
                            "attribute",
                            "share alike",
                            "attach license"
                        ]
                    }
                }
            },
            "required": [
                "id"
            ]
        },
        "Subscription": {
            "type": "object",
            "properties": {
                "key": {
                    "type": "string",
                    "readOnly": true
                },
                "datasetId": {
                    "type": "string",
                    "readOnly": true
                },
                "serviceId": {
                    "type": "string",
                    "readOnly": true
                },
                "active": {
                    "type": "boolean",
                    "readOnly": true
                }
            }
        },
        "Datasource": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string",
                    "readOnly": true
                },
                "url": {
                    "type": "string",
                    "readOnly": true
                },
                "dataset": {
                    "type": "object",
                    "readOnly": true,
                    "$ref": "#/definitions/DatasetItem"
                }
            }
        },
        "ApiResponse": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "integer",
                    "format": "int32"
                },
                "type": {
                    "type": "string"
                },
                "message": {
                    "type": "string"
                }
            }
        }
    },
    "externalDocs": {
        "description": "Find out more about MK:Smart Datahub API",
        "url": "http://datahub.mksmart.org"
    }
}