From 8be3703b5fcbf88d9c76b9562432bd94e693e35d Mon Sep 17 00:00:00 2001 From: Rosario Trischitta Date: Tue, 27 Oct 2020 12:24:20 +0100 Subject: [PATCH] Adding parameters descriptions, solves #58 adding http response status codes, solves #64 --- docs/http-response-status.rst | 25 +++++++++++++++++++++++++ docs/index.rst | 9 ++++++--- docs/response-parameters.rst | 24 ++++++++++++++++++++++++ docs/time.rst | 4 ++-- 4 files changed, 57 insertions(+), 5 deletions(-) create mode 100644 docs/http-response-status.rst create mode 100644 docs/response-parameters.rst diff --git a/docs/http-response-status.rst b/docs/http-response-status.rst new file mode 100644 index 00000000..a12716ae --- /dev/null +++ b/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 diff --git a/docs/index.rst b/docs/index.rst index 212a2028..1f3407d0 100644 --- a/docs/index.rst +++ b/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: ----------------- diff --git a/docs/response-parameters.rst b/docs/response-parameters.rst new file mode 100644 index 00000000..4aff85fe --- /dev/null +++ b/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 diff --git a/docs/time.rst b/docs/time.rst index 83c2413f..0723272c 100644 --- a/docs/time.rst +++ b/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``