added REST to docs

Author: lpabon

docs/README.md

@@ -7,21 +7,38 @@ API functions, examples, and references to multiple client libraries which can
 communicate with an OpenStorage server.
 
 ## Quick Example
-Here is a super quick example of how to get cluster information from an OpenStorage
-server using a mock container running the gRPC server and using [Polyglot](https://github.com/grpc-ecosystem/polyglot) as the gRPC client.
+Here is a quick example of how to get cluster information from an OpenStorage
+server. In this example we will be using the mock SDK container as the
+server:
+
+* Start up the container
+
+```
+$ docker run -d -p 9100:9100 -p 9110:9110 openstorage/mock-sdk-server
+```
+
+* Running the gRPC server and using [Polyglot](https://github.com/grpc-ecosystem/polyglot) as the gRPC client.
 
 ```
-$ docker run -d -p 9100:9100 openstorage/mock-sdk-server
 $ wget https://github.com/grpc-ecosystem/polyglot/releases/download/v1.6.0/polyglot.jar
 $ echo {} | java -jar polyglot.jar \
   --command=call \
   --endpoint=localhost:9100 \
   --full_method=openstorage.api.OpenStorageCluster/Enumerate
 ```
 
+* Run using the REST gRPC Gateway
+
+```
+$ curl -X POST "http://localhost:9110/v1/cluster/enumerate" \
+     -H "accept: application/json" \
+	 -H "Content-Type: application/json" \
+	 -d "{}"
+```
+
 Results in:
 
-```yaml
+```json
 {
   "cluster": {
     "status": "STATUS_OK",
@@ -41,3 +58,7 @@ Results in:
   }
 }
 ```
+
+* Check out more REST information by looking at the [Swagger](https://swagger.io) located
+at [http://localhost:9110/swagger-ui/](http://localhost:9110/swagger-ui/)
+

docs/arch.md

@@ -6,12 +6,9 @@
 The software development kit for OpenStorage is based on [gRPC](https://grpc.io/),
 allowing clients to be automatically generated in multiple languages.
 
-Different OpenStorage drivers may run the OpenStorage gRPC server on different
-locations. Please, refer to your deployed driver documentation for instructions
-on how to setup a connection to the gRPC server.
-
-In this document, examples will refer to both the [OpenStorage SDK Mock](installing.md)
-and Portworx drivers.
+Different OpenStorage drivers may run the OpenStorage gRPC and REST servers on
+different locations. Please, refer to your deployed driver documentation for
+instructions on how to setup a connection to the gRPC server.
 
 OpenStorage API calls are ment to be idempotent to ensure consistency across calls, unless
 otherwise specified.
@@ -20,5 +17,17 @@ otherwise specified.
 The gRPC bindings are created from [`api/api.proto`](https://github.com/libopenstorage/openstorage/blob/master/api/api.proto) file
 available in the OpenStorage github repo.
 
+## REST gRPC Gateway
+REST clients can benefit from the SDK server's [gRPC REST Gateway](https://github.com/grpc-ecosystem/grpc-gateway)
+which is able to translate REST calls to gRPC requests.
+
+[Swagger](https://swagger.io/) is also provided by going to the REST gRPC Gateway
+and passing the path `/swagger-ui`.
+
 ## Error Handling
 All API calls use the [standard gRPC status](https://github.com/grpc/grpc/blob/master/src/proto/grpc/status/status.proto).
+
+## OpenStorage SDK Implementations
+In this document, examples will refer to both the [OpenStorage SDK Mock](installing.md)
+and Portworx OpenStorage drivers.
+

docs/images/arch.ditaa

@@ -1,5 +1,14 @@
 +---------------+        +----------------------------------+
 |               |        |                                  |
+|  REST Client  | ---->  |         gRPC REST Gateway        |
+|               |        |                                  |
++---------------+        +----------------------------------+
+                                          |
+                                          |
+                                          |
+                                          |
++---------------+        +----------------------------------+
+|               |        |                                  |
 |  gRPC Client  | ---->  |            gRPC SDK              |
 |               |        |                                  |
 +---------------+        +----------------------------------+

docs/images/arch.png

@@ -94,8 +94,12 @@ OpenStorage provides mock SDK server as a container which can be run using the
 command:
 
 ```
-$ docker run -d -p 9100:9100 openstorage/mock-sdk-server
+$ docker run --rm -d -p 9110:9110 -p 9100:9100 openstorage/mock-sdk-server
 ```
 
+Port 9110 is the REST gRPC Gateway location for all REST calls. Port 9100 is
+the gRPC port.
+
 This will run OpenStorage server with an in-memory driver implementation called
 `fake`. You can then point your gRPC client to `localhost:9100`.
+

docs/installing.md

@@ -228,18 +228,24 @@ <h1 id="architecture">Architecture</h1>
 <h2 id="overview">Overview</h2>
 <p>The software development kit for OpenStorage is based on <a href="https://grpc.io/" target="_blank">gRPC</a>,
 allowing clients to be automatically generated in multiple languages.</p>
-<p>Different OpenStorage drivers may run the OpenStorage gRPC server on different
-locations. Please, refer to your deployed driver documentation for instructions
-on how to setup a connection to the gRPC server.</p>
-<p>In this document, examples will refer to both the <a href="installing.html">OpenStorage SDK Mock</a>
-and Portworx drivers.</p>
+<p>Different OpenStorage drivers may run the OpenStorage gRPC and REST servers on
+different locations. Please, refer to your deployed driver documentation for
+instructions on how to setup a connection to the gRPC server.</p>
 <p>OpenStorage API calls are ment to be idempotent to ensure consistency across calls, unless
 otherwise specified.</p>
 <h2 id="protocol-buffers-grpc-source-file">Protocol Buffers gRPC Source File</h2>
 <p>The gRPC bindings are created from <a href="https://github.com/libopenstorage/openstorage/blob/master/api/api.proto" target="_blank"><code>api/api.proto</code></a> file
 available in the OpenStorage github repo.</p>
+<h2 id="rest-grpc-gateway">REST gRPC Gateway</h2>
+<p>REST clients can benefit from the SDK server&apos;s <a href="https://github.com/grpc-ecosystem/grpc-gateway" target="_blank">gRPC REST Gateway</a>
+which is able to translate REST calls to gRPC requests.</p>
+<p><a href="https://swagger.io/" target="_blank">Swagger</a> is also provided by going to the REST gRPC Gateway
+and passing the path <code>/swagger-ui</code>.</p>
 <h2 id="error-handling">Error Handling</h2>
 <p>All API calls use the <a href="https://github.com/grpc/grpc/blob/master/src/proto/grpc/status/status.proto" target="_blank">standard gRPC status</a>.</p>
+<h2 id="openstorage-sdk-implementations">OpenStorage SDK Implementations</h2>
+<p>In this document, examples will refer to both the <a href="installing.html">OpenStorage SDK Mock</a>
+and Portworx OpenStorage drivers.</p>
 
 
                                 </section>
@@ -283,7 +289,7 @@ <h1 class="search-results-title">No results matching "<span class='search-query'
     <script>
         var gitbook = gitbook || [];
         gitbook.push(function() {
-            gitbook.page.hasChanged({"page":{"title":"Architecture","level":"1.3","depth":1,"next":{"title":"Installing","level":"1.4","depth":1,"path":"installing.md","ref":"installing.md","articles":[]},"previous":{"title":"Status","level":"1.2","depth":1,"path":"status.md","ref":"status.md","articles":[]},"dir":"ltr"},"config":{"plugins":["codetabs","toggle-chapters","toggle-headers","edit-link","prism","github","page-toc","-highlight","-sharing"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"prism":{},"github":{"url":"https://github.com/libopenstorage/openstorage/"},"search":{},"page-toc":{"position":"top","selector":".markdown-section h1, .markdown-section h2","showByDefault":false},"codetabs":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"toggle-headers":{},"fontsettings":{"theme":"white","family":"sans","size":2},"edit-link":{"label":"Edit this page","base":"https://github.com/libopenstorage/libopenstorage.github.io/tree/master/docs"},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":true},"toggle-chapters":{}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"OpenStorage API","gitbook":">=3.2.1"},"file":{"path":"arch.md","mtime":"2018-04-30T19:44:09.808Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-05-07T20:00:55.138Z"},"basePath":".","book":{"language":""}});
+            gitbook.page.hasChanged({"page":{"title":"Architecture","level":"1.3","depth":1,"next":{"title":"Installing","level":"1.4","depth":1,"path":"installing.md","ref":"installing.md","articles":[]},"previous":{"title":"Status","level":"1.2","depth":1,"path":"status.md","ref":"status.md","articles":[]},"dir":"ltr"},"config":{"plugins":["codetabs","toggle-chapters","toggle-headers","edit-link","prism","github","page-toc","-highlight","-sharing"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"prism":{},"github":{"url":"https://github.com/libopenstorage/openstorage/"},"search":{},"page-toc":{"position":"top","selector":".markdown-section h1, .markdown-section h2","showByDefault":false},"codetabs":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"toggle-headers":{},"fontsettings":{"theme":"white","family":"sans","size":2},"edit-link":{"label":"Edit this page","base":"https://github.com/libopenstorage/libopenstorage.github.io/tree/master/docs"},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":true},"toggle-chapters":{}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"OpenStorage API","gitbook":">=3.2.1"},"file":{"path":"arch.md","mtime":"2018-05-07T20:19:09.544Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-05-07T20:26:35.679Z"},"basePath":".","book":{"language":""}});
         });
     </script>
 </div>

w/arch.html

@@ -3424,7 +3424,7 @@ <h1 class="search-results-title">No results matching "<span class='search-query'
     <script>
         var gitbook = gitbook || [];
         gitbook.push(function() {
-            gitbook.page.hasChanged({"page":{"title":"API Refernce","level":"1.5","depth":1,"previous":{"title":"Installing","level":"1.4","depth":1,"path":"installing.md","ref":"installing.md","articles":[]},"dir":"ltr"},"config":{"plugins":["codetabs","toggle-chapters","toggle-headers","edit-link","prism","github","page-toc","-highlight","-sharing"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"prism":{},"github":{"url":"https://github.com/libopenstorage/openstorage/"},"search":{},"page-toc":{"position":"top","selector":".markdown-section h1, .markdown-section h2","showByDefault":false},"codetabs":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"toggle-headers":{},"fontsettings":{"theme":"white","family":"sans","size":2},"edit-link":{"label":"Edit this page","base":"https://github.com/libopenstorage/libopenstorage.github.io/tree/master/docs"},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":true},"toggle-chapters":{}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"OpenStorage API","gitbook":">=3.2.1"},"file":{"path":"generated-api.md","mtime":"2018-05-07T20:00:54.220Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-05-07T20:00:55.138Z"},"basePath":".","book":{"language":""}});
+            gitbook.page.hasChanged({"page":{"title":"API Refernce","level":"1.5","depth":1,"previous":{"title":"Installing","level":"1.4","depth":1,"path":"installing.md","ref":"installing.md","articles":[]},"dir":"ltr"},"config":{"plugins":["codetabs","toggle-chapters","toggle-headers","edit-link","prism","github","page-toc","-highlight","-sharing"],"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"pluginsConfig":{"prism":{},"github":{"url":"https://github.com/libopenstorage/openstorage/"},"search":{},"page-toc":{"position":"top","selector":".markdown-section h1, .markdown-section h2","showByDefault":false},"codetabs":{},"lunr":{"maxIndexSize":1000000,"ignoreSpecialCharacters":false},"toggle-headers":{},"fontsettings":{"theme":"white","family":"sans","size":2},"edit-link":{"label":"Edit this page","base":"https://github.com/libopenstorage/libopenstorage.github.io/tree/master/docs"},"theme-default":{"styles":{"website":"styles/website.css","pdf":"styles/pdf.css","epub":"styles/epub.css","mobi":"styles/mobi.css","ebook":"styles/ebook.css","print":"styles/print.css"},"showLevel":true},"toggle-chapters":{}},"theme":"default","pdf":{"pageNumbers":true,"fontSize":12,"fontFamily":"Arial","paperSize":"a4","chapterMark":"pagebreak","pageBreaksBefore":"/","margin":{"right":62,"left":62,"top":56,"bottom":56}},"structure":{"langs":"LANGS.md","readme":"README.md","glossary":"GLOSSARY.md","summary":"SUMMARY.md"},"variables":{},"title":"OpenStorage API","gitbook":">=3.2.1"},"file":{"path":"generated-api.md","mtime":"2018-05-07T20:00:54.220Z","type":"markdown"},"gitbook":{"version":"3.2.3","time":"2018-05-07T20:26:35.679Z"},"basePath":".","book":{"language":""}});
         });
     </script>
 </div>

w/generated-api.html

@@ -1,5 +1,14 @@
 +---------------+        +----------------------------------+
 |               |        |                                  |
+|  REST Client  | ---->  |         gRPC REST Gateway        |
+|               |        |                                  |
++---------------+        +----------------------------------+
+                                          |
+                                          |
+                                          |
+                                          |
++---------------+        +----------------------------------+
+|               |        |                                  |
 |  gRPC Client  | ---->  |            gRPC SDK              |
 |               |        |                                  |
 +---------------+        +----------------------------------+