From a8b9e3e0c3d67b350c7aa6a9cbe5609d962d8e40 Mon Sep 17 00:00:00 2001 From: Pawel Wodkowski Date: Mon, 9 Jul 2018 15:54:49 +0200 Subject: [PATCH] doc/jsonrpc: clarify the required, optional and error messages Change-Id: I16010ccae613d707aa7e4f34fc694c467a589fa7 Signed-off-by: Pawel Wodkowski Reviewed-on: https://review.gerrithub.io/418682 Tested-by: SPDK Automated Test System Chandler-Test-Pool: SPDK Automated Test System Reviewed-by: Jim Harris Reviewed-by: Ben Walker --- doc/jsonrpc.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/doc/jsonrpc.md b/doc/jsonrpc.md index 6acd0018f..954756a40 100644 --- a/doc/jsonrpc.md +++ b/doc/jsonrpc.md @@ -5,6 +5,55 @@ SPDK implements a [JSON-RPC 2.0](http://www.jsonrpc.org/specification) server to allow external management tools to dynamically configure SPDK components. +## Parameters + +Most of the commands can take parameters. If present, parameter is validated against its domain. If this check fail +whole command will fail with response error message [Invalid params](@ref jsonrpc_error_message). + +### Required parameters + +These parameters are mandatory. If any required parameter is missing RPC command will fail with proper error response. + +### Optional parameters + +Those parameters might be omitted. If an optional parameter is present it must be valid otherwise command will fail +proper error response. + +## Error response message {#jsonrpc_error_message} + +Each error response will contain proper message. As much as possible the message should indicate what went wrong during +command processing. + +There is ongoing effort to customize this messages but some RPC methods just return "Invalid parameters" as message body +for any kind of error. + +Code | Description +------ | ----------- +-1 | Invalid state - given method exists but it is not callable in [current runtime state](@ref rpc_start_subsystem_init) +-32600 | Invalid request - not compliant with JSON-RPC 2.0 Specification +-32601 | Method not found +-32602 | @ref jsonrpc_invalid_params +-32603 | Internal error for e.g.: errors like out of memory +-32700 | @ref jsonrpc_parser_error + +### Parser error {#jsonrpc_parser_error} + +Encountered some error during parsing request like: + +- the JSON object is malformed +- parameter is too long +- request is too long + +### Invalid params {#jsonrpc_invalid_params} + +This type of error is most common one. It mean that there is an error while processing the request like: + +- Parameters decoding in RPC method handler failed because required parameter is missing. +- Unknown parameter present encountered. +- Parameter type doesn't match expected type e.g.: given number when expected a string. +- Parameter domain check failed. +- Request is valid but some other error occurred during processing request. If possible message explains the error reason nature. + # App Framework {#jsonrpc_components_app} ## kill_instance {#rpc_kill_instance}