chore(service): update top-level api docs

Author: rokroskar

renku/service/config.py

@@ -22,12 +22,16 @@
 
 import pkg_resources
 
+# TODO: #2100 the git access error should have its own error code
 GIT_ACCESS_DENIED_ERROR_CODE = -32000
 GIT_UNKNOWN_ERROR_CODE = -32001
 
 RENKU_EXCEPTION_ERROR_CODE = -32100
 REDIS_EXCEPTION_ERROR_CODE = -32200
 
+# TODO: #2100 according to the JSON-RPC spec this code is reserved for "method not
+# found" - the invalid headers code should either be a custom code or lumped
+# under invalid params code
 INVALID_HEADERS_ERROR_CODE = -32601
 INVALID_PARAMS_ERROR_CODE = -32602
 INTERNAL_FAILURE_ERROR_CODE = -32603

renku/service/views/apispec.py

@@ -38,8 +38,9 @@
 gitlab_token_scheme = {"type": "apiKey", "name": "Authorization", "in": "header"}
 
 TOP_LEVEL_DESCRIPTION = """
-This is the API specification of the renku core service. The API follows
-JSON-RPC conventions that mirrors the functionality of the renku CLI.
+This is the API specification of the renku core service. The API follows the
+[JSON-RPC 2.0](https://www.jsonrpc.org/specification) specifications and mirrors
+the functionality of the renku CLI.
 
 The basic API is low-level and requires that the client handles project
 (repository) state in the service cache by invoking the `cache.project_clone`
@@ -51,9 +52,37 @@
 ## Higher-level interface
 
 Some API methods allow the client to defer repository management to the service.
-In these cases, the API documentation will include `project_id` _and_ `git_url`
-+ `ref` in the spec. Note that for such methods, _either_ `project_id` _or_
-`git_url` (and optionally `ref`) should be passed in the request body.
+In these cases, the API documentation will include `project_id` _and_
+`git_url`+`ref` in the spec. Note that for such methods, _either_ `project_id`
+_or_ `git_url` (and optionally `ref`) should be passed in the request body.
+
+## Responses
+
+Following the JSON-RPC 2.0 Specification, the methods all return with HTTP code
+200 and include a [response
+object](https://www.jsonrpc.org/specification#response_object) may contain
+either a `result` or an `error` object. If the call succeeds, the returned
+`result` follows the schema documented in the individual methods. In the case of
+an error, the [`error`
+object](https://www.jsonrpc.org/specification#error_object), contains a code and
+a message describing the nature of the error. In addition to the [standard JSON-RPC
+response codes](https://www.jsonrpc.org/specification#error_object), we define application-specific
+codes:
+
+```
+GIT_ACCESS_DENIED_ERROR_CODE = -32000
+GIT_UNKNOWN_ERROR_CODE = -32001
+
+RENKU_EXCEPTION_ERROR_CODE = -32100
+REDIS_EXCEPTION_ERROR_CODE = -32200
+
+INVALID_HEADERS_ERROR_CODE = -32601
+INVALID_PARAMS_ERROR_CODE = -32602
+INTERNAL_FAILURE_ERROR_CODE = -32603
+
+HTTP_SERVER_ERROR = -32000
+```
+
 """
 
 spec = APISpec(