Adding parameters descriptions, solves #58

adding http response status codes, solves #64

docs/http-response-status.rst

@@ -0,0 +1,25 @@
+HTTP response status of the ohsome API
+======================================
+
+List of HTTP status codes and respective descriptions of the ohsome API.
+
+2xx success
+-----------
+
+* ``200 OK`` - standard response for successfully GET and POST requests
+
+4xx client errors
+-----------------
+
+* ``400 Bad Request`` - the ohsome API cannot or will not process the request due to client error (e.g. malformed request syntax)
+* ``401 Unauthorized`` - the client does not have valid authentication credentials for the target resource
+* ``404 Not Found``-  the requested resource coud not be found
+* ``405 Method not allowed`` - a request method is not supported (e.g. a POST request for resources which accept only GET requests)
+* ``413 Payload Too Large`` - the request is larger than the ohsome API is willing or able to process.
+
+5xx server errors
+-----------------
+
+* ``500 Internal Server Error``- generic error message, given when an unexpected condition in the ohsome API was encountered
+* ``501 Not Implemented``	- the ohsome API either does not recognize the request method, or it lacks the ability to fulfil the request
+* ``503 Service Unavailable`` - the ohsome API cannot handle the request (e.g. because it is overloaded or down for maintenance); temporary state

docs/index.rst

@@ -21,14 +21,17 @@ Welcome to the documentation of the ohsome API!
 ..   autodocs
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
    :caption: Additional Information:
-   :hidden:
-
+
    boundaries
    group-by
    time
    filter
+   response-parameters
+   http-response-status
+
+..   autodocs
    
 Additional Links:
 -----------------

docs/response-parameters.rst

@@ -0,0 +1,24 @@
+Response Parameters
+===================
+
+List and description of response parameters.
+
+Extraction Endpoints
+--------------------
+
+* ``@osmId`` - id of the OSM feature with its type (node/way/relation)
+* ``@validFrom`` - indicates when a creation or change of this feature with these exactly attributes and geometry was made; has the same value as the fromTimestamp if the creation/change happened before the requested timestamp
+* ``@validTo`` - indicates until when this feature with these exactly attributes and geometry stayed unchanged or undeleted; has the same value as the fromTimestamp if the creation/change happened before the requested timestamp
+
+Contribution Endpoints
+----------------------
+
+* ``@osmId`` - id of the OSM feature with its type (node/way/relation)
+* ``@osmType``- type (node/way/relation) of OSM feature
+* ``@timestamp`` - indicates when this contribution occurred
+* ``@version`` - version of the feature
+* ``@changesetId``- id assigned to a changeset
+* ``@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

docs/time.rst

@@ -6,8 +6,8 @@ ISO-8601 conform timestring(s).
 
 .. note:: The ohsome API only supports the UTC time zone (Z).
 
-Supported time formats:
------------------------
+Supported time formats
+----------------------
 
 * timestamp: ``2014-01-01``
 * list of timestamps: ``2014-01-01,2015-07-01,2018-10-10``