Spec: Server interaction approach

This spec describes the approach of interaction with OpenStack
API which should be used by the library.

Change-Id: Iedc85d5bb2518b4099177d6db31abddbabafa03b

doc/source/specs/server_interaction.rst

@@ -0,0 +1,107 @@
+::
+
+  Copyright 2016 Mirantis, Inc.
+
+  This work is licensed under a Creative Commons Attribution 3.0
+  Unported License.
+  http://creativecommons.org/licenses/by/3.0/legalcode
+
+..
+
+=======================================
+Interaction with OpenStack Services API
+=======================================
+
+We need to agree on the approach that will be used for interaction with
+OpenStack services API that would fit needs of library users.
+
+Problem Description
+===================
+
+Choice of a method of communication with OpenStack API it the key decision
+for the project. The main requirement here is that the chosen method must be
+isomorphic - the same code must work both with the latest versions of popular
+browsers (Chrome 50, Firefox 47) and Node v4.
+
+Proposed Change
+===============
+
+This project will use window.fetch() function to interact with OpenStack API.
+fetch() is a modern XMLHTTPRequest with a frendlier interface, which is
+supported by majority of the browsers. For browsers which don't support it,
+there is a very popular `polyfill`_ from Github.
+
+For node.js `node-fetch`_ module should be used. It implements the same fetch()
+interface which works on node.js environments.
+
+fetch() should be called directly from clients, without any extra wrappers.
+Such wrapper could be added later, for example, to handle caching and parallel
+requests, but there should be a separate spec for this.
+
+Alternatives
+------------
+
+There are a few isomorphic libraries for making HTTP requests and interacting
+with REST API. I think the project should stick to fetch() because:
+
+* Libraries for making HTTP requests (like `superagent`_) were mostly created
+  when there was no fetch(). They mostly do the same thing - provide a
+  friendlier interface over XMLHTTPRequest. Since there is fetch() standard,
+  it makes very little sense to use them.
+
+* There is `isomorphic-fetch`_ module, which is more popular than
+  `node-fetch`_. It implements XMLHttpRequest to node.js environment to run
+  browser-specific polyfill. Approach of `node-fetch`_ which implements fetch()
+  using node "http" module (without implementing XMLHTTPRequest) is
+  considered simpler.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  vkramskikh
+
+Gerrit Topic
+------------
+
+Use Gerrit topic "neverland" for all patches related to this spec.
+
+.. code-block:: bash
+
+    git-review -t neverland
+
+Work Items
+----------
+
+* Add node-fetch to the project dependencies.
+
+Documentation
+-------------
+
+The process of creating a new OpenStack service client using the approach
+described in this spec should be documented.
+
+Security
+--------
+
+None
+
+Testing
+-------
+
+Tests will be written for node and browsers.
+
+Dependencies
+============
+
+Since node-fetch is a project dependency, but it shouldn't be included in the
+browser build, most likely we need to implement transpiling and build systems
+first.
+
+.. _polyfill: https://github.com/github/fetch
+.. _node-fetch: https://github.com/bitinn/node-fetch
+.. _superagent: https://github.com/visionmedia/superagent
+.. _isomorphic-fetch: https://github.com/matthew-andrews/isomorphic-fetch