From 981e01684e3c2d2ce1d3f20432b6bd3af4741e89 Mon Sep 17 00:00:00 2001
From: Michael Hanselmann <hansmi@google.com>
Date: Fri, 20 Aug 2010 15:13:11 +0200
Subject: [PATCH] Document non-standard usage of JSON in RAPI
This was requested in issue 118.
Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>
---
doc/rapi.rst | 33 +++++++++++++++++++++++++++++++++
1 file changed, 33 insertions(+)
diff --git a/doc/rapi.rst b/doc/rapi.rst
index fcf955abd..b9fe651d9 100644
--- a/doc/rapi.rst
+++ b/doc/rapi.rst
@@ -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?
------------
--
GitLab