Commit 981e0168 authored by Michael Hanselmann's avatar Michael Hanselmann

Document non-standard usage of JSON in RAPI

This was requested in issue 118.
Signed-off-by: default avatarMichael Hanselmann <hansmi@google.com>
Reviewed-by: default avatarIustin Pop <iustin@google.com>
parent 2175e25d
......@@ -72,6 +72,39 @@ HTTP Basic authentication as per RFC2617_ is supported.
.. _RFC2617: http://tools.ietf.org/rfc/rfc2617.txt
A note on JSON as used by RAPI
++++++++++++++++++++++++++++++
JSON_ as used by Ganeti RAPI does not conform to the specification in
:rfc:`4627`. Section 2 defines a JSON text to be either an object
(``{"key": "value", …}``) or an array (``[1, 2, 3, …]``). In violation
of this RAPI uses plain strings (``"master-candidate"``, ``"1234"``) for
some requests or responses. Changing this now would likely break
existing clients and cause a lot of trouble.
.. highlight:: ruby
Unlike Python's `JSON encoder and decoder
<http://docs.python.org/library/json.html>`_, other programming
languages or libraries may only provide a strict implementation, not
allowing plain values. For those, responses can usually be wrapped in an
array whose first element is then used, e.g. the response ``"1234"``
becomes ``["1234"]``. This works equally well for more complex values.
Example in Ruby::
require "json"
# Insert code to get response here
response = "\"1234\""
decoded = JSON.parse("[#{response}]").first
Short of modifying the encoder to allow encoding to a less strict
format, requests will have to be formatted by hand. Newer RAPI requests
already use a dictionary as their input data and shouldn't cause any
problems.
PUT or POST?
------------
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment