swagger: '2.0' info: version: "1.0.0" title: FetchClimate API description: Fetching service configuration, operation logs and quering the data contact: name: Dmitry A. Grechka email: dmitryg@itis.cs.msu.ru host: fc.itis.cs.msu.ru tags: - name: Operator description: Service health, load, logs, etc. - name: Regular user description: Getting info about published data and fetching the data schemes: - http paths: /api/status: get: tags: - Regular user description: Retrieves the information about particular query performed to the service beforehand parameters: - name: hash in: query description: Hash value of the request required: true type: string produces: - application/xml - application/json responses: 200: description: Successful response schema: $ref: '#/definitions/QueryStatus' /api/configuration: get: tags: - Regular user description: Retrieves the available data sets and variables produces: - application/xml - application/json parameters: - name: timestamp in: query description: A timestemp in ISO 8601 format (e.g. "2016-01-01T12:00:00Z") that describes time for which to retrieve the effective configuration required: false type: string responses: 200: description: Successful response schema: title: Service configuration snapshot type: object properties: FetchConfiguration: type: object properties: DataSources: type: array items: type: object properties: DataSourceDefinition: type: object properties: Copyright: type: string description: A copyright notice about the data set Description: type: string description: Full textural description of the data set ID: type: integer description: Unique numeric identifier (within current FC instance) of the data set. Used in the provenance reports Name: type: string description: Short unique string identifier (within current FC instance) of the data set ProvidedVariables: type: array items: type: string description: identifier of the variable EnvironmentalVariables: type: array items: type: object properties: Description: type: string description: Full textural description of the variable Name: type: string description: Short unique identifier of the variable Units: type: string description: A description of units in which the values for this variable are returned TimeStamp: type: string description: A timestamp in ISO 8601 format (e.g. "2016-01-01T12:00:00Z") that describes time for which the configuration corresponds 400: description: | Bad request. Commonly happens due to too early timestamp. e.g. timestamp before the service was deployed and configured /api/compute: post: tags: - Regular user description: Submits a query for processing consumes: - application/json produces: - application/json parameters: - name: Data query in: body required: true description: Specification of the fetch schema: type: object properties: EnvironmentVariableName: type: string title: textural identifier of the variable to fetch ReproducibilityTimestamp: type: integer title: UNIX time for which reproduce the result. can be 253404979199999 which idicates most recent service configuration ParticularDataSources: title: permeted sources of data description: can be empty. This indicates that all available datasets can be used type: array items: title: Dataset textural identifier type: string Domain: title: Spatial and temporal specifications for data to fetch type: object properties: SpatialRegionType: type: string enum: - CellGrid - PointGrid - Points - Cells description: | 'Points' indicates that Lats,Lats2,Lons,Lons2 fields describe point set. 'Cells' indicates that Lats,Lats2,Lons,Lons2 fields describe cells (rectangles) set. 'PointGrid' indicates that Lats,Lats2,Lons,Lons2 fields describe rectangular grid of points. 'CellGrid' indicates that Lats,Lats2,Lons,Lons2 fields describe rectangular grid of cells (rectangles formed by grid nodes). Lats: title: Latitudes array type: array items: type: number format: float description: | if SpatialRegionType='Points' then Lats and Lons fields contain arrays that describe the requested point set. The arrays lengths are equal. Their length is equal to the number of points in the point set. if SpatialRegionType='PintGrid' then Lats and Lons fields describe grid. Lats array describes latitudes of grid nodes, Lons array describe longitudes of grid nodes. For each grid node the value will be fetched. There will be Length(Lats)xLength(Lons) values fetched. if SpatialRegionType='CellGrid' then Lats and Lons fields describe grid. Lats array describes latitudes of grid nodes, Lons array describe longitudes of grid nodes. Grid nodes form rectangular areas between them. These areas are called cells. For each grid cell the mean value is fetched. There will be (Length(Lats)-1)x(Length(Lons)-3) values fetched. if SpatialRegionType='Cells' then Lats, Lons, Lats2,Lons2 fields contain arrays that describe the requested cells (rectangular areas) set. All four arrays lengths are equal. Their length is equal to the number of cells in the cell set. Each cell is defined as rectangle with latitudes between lat[i] and lat2[i], longitudes between lon[i] and lon2[i]. Lons: title: Longitudes array type: array items: type: number format: float description: | if SpatialRegionType='Points' then Lats and Lons fields contain arrays that describe the requested point set. The arrays lengths are equal. Their length is equal to the number of points in the point set. if SpatialRegionType='PintGrid' then Lats and Lons fields describe grid. Lats array describes latitudes of grid nodes, Lons array describe longitudes of grid nodes. For each grid node the value will be fetched. There will be Length(Lats)xLength(Lons) values fetched. if SpatialRegionType='CellGrid' then Lats and Lons fields describe grid. Lats array describes latitudes of grid nodes, Lons array describe longitudes of grid nodes. Grid nodes form rectangular areas between them. These areas are called cells. For each grid cell the mean value is fetched. There will be (Length(Lats)-1)x(Length(Lons)-3) values fetched. if SpatialRegionType='Cells' then Lats, Lons, Lats2,Lons2 fields contain arrays that describe the requested cells (rectangular areas) set. All four arrays lengths are equal. Their length is equal to the number of cells in the cell set. Each cell is defined as rectangle with latitudes between lat[i] and lat2[i], longitudes between lon[i] and lon2[i]. Lats2: type: array items: type: number format: float description: | Valid only for SpatialRegionType='Cells', must be null otherwise This field is considered only if SpatialRegionType='CellGrid', ignored otherwise, can be null. if SpatialRegionType='Cells' then Lats, Lons, Lats2,Lons2 fields contain arrays that describe the requested cells (rectangular areas) set. All four arrays lengths are equal. Their length is equal to the number of cells in the cell set. Each cell is defined as rectangle with latitudes between lat[i] and lat2[i], longitudes between lon[i] and lon2[i]. Lon2: type: array items: type: number format: float description: | Valid only for SpatialRegionType='Cells', must be null otherwise if SpatialRegionType='Cells' then Lats, Lons, Lats2, Lons2 fields contain arrays that describe the requested cells (rectangular areas) set. All four arrays lengths are equal. Their length is equal to the number of cells in the cell set. Each cell is defined as rectangle with latitudes between lat[i] and lat2[i], longitudes between lon[i] and lon2[i]. Mask: title: Computation mask type: - object description: | A boolean array that matches dimensions of data array to be returned. 'true' values indicate that in these position data must be computed. 'false' indicate that in these positions the computaion can not be performed, the returned data values in these poitions can be arbitrary. Can be null. null indicates that all values are needed, nothing can be omitted TimeRegion: type: object title: Temporal specification properties: IsIntervalsGridDays: type: boolean default: true description: | Controls how Days property transfors into days within each year series dimension. Consider Days = [1,11,21]. Setting IsIntervalsGridDays to true describes the exclusive intervals between day numbers. e.g. [1,10],[11,20] within each requested year; setting IsIntervalsGridDays to false describes individual day numbers. e.g. [1],[11],[21] within each requested year. IsIntervalsGridHours: type: boolean default: true description: | Controls how Hours property transfors into hours within each day series dimension. Consider Hours = [0,6,12,18,24]. Setting IsIntervalsGridHours to true describes the inclusive intervals between hours. e.g. [0,6],[6,12],[12,18],[18,24] within each requested day; setting IsIntervalsGridHours to false describes individual time moments. e.g. [0],[6],[12],[18],[24] within each requested day. IsIntervalsGridYears: type: boolean default: true description: | Controls how Years property transfors into years dimension. Consider Hours = [1961,1971,1981]. Setting IsIntervalsGridYears to true describes the inclusive intervals between years specified. e.g. [1961,1970],[1971,1980]; setting IsIntervalsGridYears to false describes individual years. e.g. [1961],[1971],[1981]. Years: type: array description: An array to form Years dimension. See the rule for forming the Years dimension in IsIntervalsGridYears description. items: type: integer Days: type: array description: An array to form Days dimension. See the rule for forming the Days dimension in IsIntervalsGridDays description. items: type: integer Hours: type: array description: An array to form Hours dimension. See the rule for forming the Hours dimension in IsIntervalsGridHours description. items: type: integer responses: 200: description: Successful response schema: $ref: '#/definitions/QueryStatus' /jsproxy/schema: get: tags: - Regular user description: | Extracts the schema of the Dmitrov data set. See http://research.microsoft.com/en-us/um/cambridge/groups/science/tools/dmitrov/ for more info about Dmitrov. produces: - application/json - application/xml parameters: - name: uri in: query required: true type: string description: Dmitrov URI to get schema for. responses: 200: description: Successful response schema: title: Full data set schema type: object properties: SerializableDataSetSchema: type: object description: Container object properties: Dimensions: title: Dimension space of the data set type: array items: $ref: '#/definitions/DataSetDimension' Metadata: title: whole data set wide metadata entries type: array items: $ref: '#/definitions/MetaDataEntry' Variables: title: data variables type: array items: xml: name: SerializableVariableSchema title: single variable definition type: object properties: Dimensions: title: dimensions on which the variable is defined type: array items: title: dimension name type: string Metadata: title: varaible metadata entries type: array items: $ref: '#/definitions/MetaDataEntry' Name: type: string title: textural identifier of the variable Size: type: integer title: Size (in bytes) of single variable element TypeString: type: string title: .NET type identifier 500: description: Schema extraction failure /jsproxy/data: get: tags: - Regular user description: | Proxy that converts Dmitrov Data sets to JSON. Can be used to extract query results. See http://research.microsoft.com/en-us/um/cambridge/groups/science/tools/dmitrov/ for more info about Dmitrov. produces: - application/json parameters: - name: uri in: query required: true type: string description: Dmitrov URI to get data from. - name: variables in: query required: true type: string description: Comma separated list of variables to extract responses: 200: description: Successful data fetching schema: title: Container of variable data description: | Each field of the object correspond to each requested variable. Each field is named as requested variable. Each field is N-dimentional array (presentd as jagged array). Number of diemension depends on the variable definition. See /jsproxy/schema endpoint which provides the information about variables dimensions. type: object 500: description: Data fetching failure /api/load: get: tags: - Operator description: Retrieves the current service load status. The count of currently processing queries. The count of queries in queue. produces: - application/xml responses: 200: description: Successful response schema: title: Load of the service type: object properties: SystemStatus: type: object properties: activeParts: type: integer activeRequests: type: integer pendingParts: type: integer pendingRequests: type: integer /logs: get: tags: - Operator description: | Gets logs messages of service operation produces: - text/html - text/plain parameters: - name: format in: query description: The format of data to extract. Can be only "csv" or "html" for now. Default is "html" required: false type: string - name: days in: query description: For how many days since now the logs are extracted required: false type: integer minimum: 1 maximum: 365 - name: hash in: query description: Retrieve only messages related to specified query hash required: false type: string responses: 200: description: Successful response schema: title: HTML/CSV content with operation logs type: string definitions: QueryStatus: title: Query status string type: string description: | The following variables can be found in format section: {result_url} - the Dmitrov dataset URL. You can pass it to /jsproxy/schema, /jsproxy/data endpoints to obtain the data in JSON {error_message} - textural description of the error {percentage} - the progress indicator {query_hash} - replicates the hash specified in the parameters {position_in_queue} - how many queries are in the queue before the current format: | 'completed={result_url}' : query successfuly processed. You can download results via /jsproxy/schema, /jsproxy/data endpoints 'fault={error_message}' : error occurred during query proccesing 'progress={percentage}%; hash={query_hash}' : query is currently processed 'pending={position_in_queue}; hash={query_hash}' : query is in queue to be processed DataSetDimension: title: Single dimension definition type: object xml: name: SerializableDimension properties: Length: type: integer Name: title: string identifier of the dimension type: string MetaDataEntry: type: object xml: name: KeyValueOfstringObjectWithTypeStringNkIIWh0I properties: Key: type: string Value: type: object properties: TypeString: type: string title: .NET type identifier Value: type: string title: .NET serialized identifier