Extend info on timeout parameter

docs/endpoints.rst

@@ -22,7 +22,7 @@ Aggregation Endpoints
    :query filter: combines several attributive filters: OSM type, geometry (simple feature) type, as well as the OSM tag; See filter_
    :query format: 'json' or 'csv'; default: 'json'
    :query showMetadata: add additional metadata information to the response: 'true', 'false', 'yes', 'no'; default: 'false'
-   :query timeout: custom timeout to limit the processing time in seconds; default: empty
+   :query timeout: custom timeout to limit the processing time in seconds; default: dependent on server settings, retrievable via the /metadata request
    :query types: Deprecated! Use **filter** parameter instead! Old parameter which allowed to specify OSM type(s) ‘node’ and/or ‘way’ and/or ‘relation’ OR simple feature type(s) ‘point’ and/or ‘line’ and/or 'polygon’ and/or 'other'; default: all three OSM types
    :query keys: Deprecated! Use **filter** parameter instead! Old parameter which allowed to specify OSM key(s) given as a list and combined with the 'AND' operator; default: empty
    :query values: Deprecated! Use **filter** parameter instead! Old parameter which allowed to specify OSM value(s) given as a list and combined with the 'AND' operator; values(n) MUST fit to keys(n); default: empty
@@ -1919,6 +1919,7 @@ Get metadata of the underlying OSHDB data
           "text" : "© OpenStreetMap contributors"
         },
         "apiVersion" : "1.2.3",
+        "timeout": 600.0,
         "extractRegion" : {
           "spatialExtent" : {
             "type" : "Polygon",

docs/response-parameters.rst

@@ -1,21 +1,29 @@
 Response Parameters
 ===================
 
-Descriptions of the custom response parameters that are marked with a leading ``@`` for the 
-data extraction and contributions endpoints.
+Description of the response parameters.
 
 General Parameters
 ------------------
 
-* ``@osmId`` - id of the OSM feature with its type (node/way/relation)
-* ``@version`` - version of the feature
-* ``@changesetId``- id assigned to a changeset
-* ``@osmType``- type (node/way/relation) of OSM feature
+Description of parameters that are present in every response.
 
+* ``attribution`` - copyrights and attribution
+* ``apiVersion`` - version of the ohsome API
+
+Aggregation Parameters
+----------------------
 
 Extraction Parameters
 ---------------------
 
+Descriptions of the custom response parameters that are marked with a leading ``@``.
+
+* ``@osmId`` - id of the OSM element, including its type (e.g. node/1)
+* ``@version`` - version number of the OSM element
+* ``@changesetId`` - id of the OSM changeset which last increased the version of this OSM element
+* ``@osmType`` - type of the OSM element (NODE, WAY or RELATION)
+
 **specific for /elements**
 
 * ``@snapshotTimestamp`` - describes for which timestamp a snapshot of this feature was requested
@@ -29,8 +37,24 @@ Extraction Parameters
 Contribution Parameters
 -----------------------
 
+Descriptions of the custom response parameters that are marked with a leading ``@``.
+
+* ``@osmId`` - id of the OSM element, including its type (e.g. node/1)
+* ``@version`` - version of the OSM element
+* ``@changesetId`` - id of the OSM changeset where the contribution was performed
+* ``@osmType`` - type of the OSM element (NODE, WAY or RELATION)
 * ``@timestamp`` - indicates when this contribution occurred
 * ``@creation``	- contribution type; indicates if this feature is newly created (true); cannot occur in combination with other contribution types
 * ``@geometryChange`` - contribution type; indicates if the geometry of this feature has changed (true); can occur in combination with @tagChange
 * ``@tagChange``- contribution type; indicates if the tag of this feature has changed (true); can occur in combination with @geometryChange
 * ``@deletion`` - contribution type; indicates if the feature is deleted (true); cannot occur in combination with other contribution types
+
+Metadata
+--------
+
+* ``timeout`` - limit of the processing time in seconds
+* ``spatialExtent`` - spatial boundary of the OSM data in the underlying OSHDB
+* ``temporalExtent`` - timeframe of the OSM data in the underlying OSHDB
+* ``fromTimestamp`` - temporal starting point
+* ``toTimestamp`` - temporal ending point
+* ``replicationSequenceNumber`` - precise state of the OSM data contained in the underlying OSHDB, expressed as the id of the last applied (hourly) diff file from planet.openstreetmap.org

src/main/java/org/heigit/ohsome/ohsomeapi/executor/MetadataRequestExecutor.java

@@ -25,7 +25,7 @@ public static MetadataResponse executeGetMetadata(HttpServletRequest servletRequ
     }
     return new MetadataResponse(
         new Attribution(ExtractMetadata.attributionUrl, ExtractMetadata.attributionShort),
-        Application.API_VERSION,
+        Application.API_VERSION, ExtractMetadata.timeout,
         new ExtractRegion(ExtractMetadata.dataPolyJson,
             new TemporalExtent(ExtractMetadata.fromTstamp, ExtractMetadata.toTstamp),
             ExtractMetadata.replicationSequenceNumber));

src/main/java/org/heigit/ohsome/ohsomeapi/oshdb/ExtractMetadata.java

@@ -1,6 +1,7 @@
 package org.heigit.ohsome.ohsomeapi.oshdb;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import org.heigit.ohsome.ohsomeapi.inputprocessing.ProcessingData;
 import org.locationtech.jts.geom.Geometry;
 
 /** Holds the metadata that is derived from the data-extract. */
@@ -13,6 +14,7 @@ public class ExtractMetadata {
   public static Geometry dataPoly = null;
   public static JsonNode dataPolyJson = null;
   public static int replicationSequenceNumber;
+  public static double timeout = ProcessingData.getTimeout();
 
   private ExtractMetadata() {
     throw new IllegalStateException("Utility class");

src/main/java/org/heigit/ohsome/ohsomeapi/output/metadataresponse/MetadataResponse.java

@@ -19,10 +19,12 @@ public class MetadataResponse {
 
   @ApiModelProperty(notes = "License and copyright info", required = true, position = 0)
   private Attribution attribution;
-  @ApiModelProperty(notes = "Version of this api", required = true, position = 0)
+  @ApiModelProperty(notes = "Specific version of this API", required = true, position = 1)
   private String apiVersion;
+  @ApiModelProperty(notes = "Maximal response timeout in seconds", required = true, position = 2)
+  private double timeout;
   @ApiModelProperty(
-      notes = "Extract region object holding the spatial|temporal extend + attribution",
-      required = true)
+      notes = "Extract region object holding the spatial|temporal extent + attribution",
+      required = true, position = 3)
   private ExtractRegion extractRegion;
 }

src/test/java/org/heigit/ohsome/ohsomeapi/controller/GetControllerTest.java

@@ -6,6 +6,7 @@
 import static org.junit.Assume.assumeTrue;
 
 import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.node.JsonNodeType;
 import java.io.IOException;
 import java.util.Arrays;
 import java.util.LinkedList;
@@ -16,6 +17,7 @@
 import java.util.stream.StreamSupport;
 import org.apache.commons.csv.CSVRecord;
 import org.heigit.ohsome.ohsomeapi.Application;
+import org.heigit.ohsome.ohsomeapi.inputprocessing.ProcessingData;
 import org.junit.AfterClass;
 import org.junit.BeforeClass;
 import org.junit.Test;
@@ -65,8 +67,13 @@ public void getMetadataTest() {
     TestRestTemplate restTemplate = new TestRestTemplate();
     ResponseEntity<JsonNode> response =
         restTemplate.getForEntity(server + port + "/metadata", JsonNode.class);
-    assertTrue(!response.getBody().get("extractRegion").get("temporalExtent").get("toTimestamp")
-        .asText().equals("2018-01-01T00:00:00"));
+    assertEquals("https://ohsome.org/copyrights",
+        response.getBody().get("attribution").get("url").asText());
+    assertEquals(ProcessingData.getTimeout(), response.getBody().get("timeout").asDouble(), 1e-3);
+    assertEquals(JsonNodeType.OBJECT,
+        response.getBody().get("extractRegion").get("spatialExtent").getNodeType());
+    assertTrue(response.getBody().get("extractRegion").get("temporalExtent").isContainerNode());
+    assertTrue(response.getBody().get("extractRegion").get("replicationSequenceNumber").isInt());
   }
 
   /*