Merge pull request #12 from bwilkins/BR_ISI_SDK_PUBLISHING_README

Prepare bindings generator repo for publication
Isilon · Jun 10, 2016 · 2714622 · 2714622
2 parents db4efdd + 55538e0
commit 2714622
Show file tree

Hide file tree

Showing 11 changed files with 133 additions and 73 deletions.
diff --git a/README.md b/README.md
@@ -1,62 +1,77 @@
-# isilon-swagger
-Tools to allow integration of Isilon REST APIs with Swagger (swagger.io)
+# Isilon Software Development Kit (isi-sdk)
+Language bindings for the OneFS API and tools for building them
 
-#### To generate a swagger config for PAPI:
+This repository is part of the Isilon SDK.  It includes language bindings for easier programmatic access to the OneFS RESTful API for cluster configuration (on your cluster this is the RESTful API made up of all the URIs underneath https://[cluster]:8080/platform/*, also called the "Platform API" or PAPI").
 
-1. Clone this repository.
-2. Find a OneFS cluster, get the IP address.
-3. Run `python create_swagger_config.py -i <cluster-ip-address> -o <output_file> --username <username> --password <password>` <br> if you omit --username or --password then it will prompt you
+You can download the language bindings for Python from the "releases" page of this repo (the link is on the main "code" tab on the bar of links just below the project description).  If you just want to access PAPI more easily from your Python programs, these language bindings may be all you need, and you can follow the instructions and example below to get started.
 
-This will automatically generate a swagger config <output_file> based on the ?describe responses from the PAPI handlers on your node.  Swagger tools can now use this config to create language bindings and documentation.
+This repository also includes tools to build PAPI bindings yourself for a large range of other programming languages.  For more info see the [readme.dev.md](readme.dev.md) file in this directory.
 
-#### To generate python PAPI bindings using the swagger config:
-1. Clone the swagger-codegen repo from https://github.com/swagger-api/swagger-codegen
-2. Follow the relevant instructions there (in the README.md) to install the codegen java program.  In my case I did "apt-get install maven" to get maven then ran "mvn package" to install codegen.
-3. Run codegen on the swagger_config.json file generated above.  You can also use one of the "example_output.json" available in the root directory of this repo.  For example:
+### Installing the pre-built Python PAPI bindings
 
-`java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i output.json -l python -o ./papi_client/python -c swagger-codegen-config.json`
+1. Download the latest package from the "releases" page of this repo.
 
-#### To generate API documentation from the swagger config:
-1. Generate a PAPI swagger config as above, or use the "example_output.json" in this repo.
-2. Install codegen as described above.
-3. Use codegen with the language specified as "nodejs" or "html" to output API docs instead of a bindings library for a language, for example:
+2. Install via [Setuptools](http://pypi.python.org/pypi/setuptools).  For example, unzip the package archive to a directory and from there run:
 
-``java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i swagger_config.json -l dynamic-html -o ./papi_doc -c swagger-codegen-config.json`
+```sh
+python setup.py install --user
+```
+(or `sudo python setup.py install` to install the package for all users)
 
-Note that you do not need to have NodeJS installed to browse the "nodejs" style dynamic output docs - just go into the generated directory structure, find index.html, and open it in your browser.  You can see an example of my most recently generated docs at:
+You may need to install the Python [Setuptools](http://pypi.python.org/pypi/setuptools) on your system, if they are not already installed. For instructions, see http://pypi.python.org/pypi/setuptools.
 
-`http://cribsbiox.west.isilon.com/home/bwilkins/swagger/papi_doc_dynamic/docs/`
+Then at a Python prompt or in your Python programs, import the package:
+```python
+import isi_sdk_8_0 # or isi_sdk_7_2, depending on the release you downloaded
+```
 
-#### To write code with the python PAPI bindings:
-1. Generate a python PAPI bindings package using the above steps, or just use the one I've put at `http://cribsbiox.west.isilon.com/home/bwilkins/swagger/papi_client/python/`
-2. Install the library with `python setup.py install --user` from the `papi_client` directory
-3. In your python programs, you can now write code like the following to interact with PAPI handlers:
+## Example program
 
-```
-import isi_sdk
+Here's an example of using the Python PAPI bindings to retrieve a list of NFS exports from your cluster:
+
+```python
+import isi_sdk_8_0 # or isi_sdk_7_2, depending on the release you downloaded
+from isi_sdk_8_0.rest import ApiException
+from pprint import pprint
 import urllib3
 urllib3.disable_warnings()
 
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk_8_0.configuration.username = "YOUR_USERNAME"
+isi_sdk_8_0.configuration.password = "YOUR_PASSWORD"
+isi_sdk_8_0.configuration.verify_ssl = False
 
 # configure host
-host = "https://10.7.160.60:8080"
-apiClient = isi_sdk.ApiClient(host)
-protocolsApi = isi_sdk.ProtocolsApi(apiClient)
+host = "https://YOUR_CLUSTER_HOSTNAME_OR_NODE_IP_ADDRESS:8080"
+api_client = isi_sdk_8_0.ApiClient(host)
+protocols_api = isi_sdk_8_0.ProtocolsApi(api_client)
 
 # get all exports
-nfsExports = protocolsApi.list_nfs_exports()
-print "NFS Exports:\n" + str(nfsExports)
-
+sort = "description"
+limit = 50
+dir = "ASC"
+try: 
+    api_response = protocols_api.list_nfs_exports(sort=sort, limit=limit, dir=dir)
+    pprint(api_response)
+except ApiException as e:
+    print "Exception when calling ProtocolsApi->list_nfs_exports: %s\n" % e
 ```
 
-For more examples of coding to the python PAPI bindings, see the test scripts in the `tests/` subdirectory of this repo.
+For more examples of coding to the Python PAPI bindings, see the test scripts in the `tests/` subdirectory of this repo.
+
+### Bindings Documentation
+
+The most up-to-date documentation for the language bindings is included in the root directory of your downloaded release package (or of your own generated bindings if you've generated your own using the instructions at [readme.dev.md](readme.dev.md)).  It is a set of markdown files starting with the README.md in the root directory of the package.
+
+We intend to also publish online docs as part of the build process for this repo's releases, but we haven't finished setting that up yet.  Meanwhile, if you really need online docs, some are still available at the legacy bindings repos linked below, but these will gradually be going out of sync with the latest bindings releases in this repo.
+
+- [Legacy 8.0 Bindings Docs](https://github.com/Isilon/isilon_sdk_8_0_python)
+
+- [Legacy 7.2 Bindings Docs](https://github.com/Isilon/isilon_sdk_7_2_python)
+
+### Other Isilon SDK and API links:
 
-As you code, you may want to generate docs with the steps above, or refer to the docs I generated and put at:
+* For OneFS API reference documents, discussions, and blog posts, refer to the [OneFS SDK Info Hub](https://community.emc.com/docs/DOC-48273).
+* To browse the Isilon InsiqhtIQ statistics API, refer to the [Stat Key Browser](https://github.com/isilon/isilon_stat_browser.git) Github repository.
 
-`http://cribsbiox.west.isilon.com/home/bwilkins/swagger/papi_doc_dynamic/docs/`
 
-In some cases just looking at the actual swagger config will be more informative though because currently the generated "NodeJS" style docs obscure the full format of a lot of PAPI's return objects.  I'm looking into different swagger documentation tools.
diff --git a/readme.dev.md b/readme.dev.md
@@ -0,0 +1,34 @@
+# Isilon Software Development Kit (isi-sdk)
+Building language bindings using the OpenAPI config generator
+
+This document describes how to use the scripts in the isi-sdk repository to generate your own language bindings for the Isilon OneFS configuration API.  This API is made up of all the URIs underneath https://[cluster]:8080/platform/*, also called the "Platform API" or PAPI".
+
+The scripts create a configuration file compatible with the OpenAPI Specification (formerly known as swagger, and we will continue to call the configuration file the "swagger config" here for now).  More info about the OpenAPI Specification [here](https://github.com/OAI/OpenAPI-Specification).
+
+The swagger config can then be used by the [swagger codegen tool](https://github.com/swagger-api/swagger-codegen) to generate language bindings for [various languages](https://github.com/swagger-api/swagger-codegen#customizing-the-generator).  This is how the Python bindings in the "releases" page of this repo are generated when updates to our scripts are made.  If you just need the Python bindings, you can download the latest from the "releases" page (the link is on the main "code" tab of the github repo on the bar of links just below the project description).
+
+The walkthrough below will guide you through the generation process step by step in case you want to build your own bindings.  You will need access to a cluster running OneFS version 7.2 or later (earlier versions not tested).
+
+### To generate the swagger config for PAPI:
+
+1. Clone this repository.
+2. Find a OneFS cluster, get the IP address.
+3. Run `python components/create_swagger_config.py -i <cluster-ip-address> -o <output_file> --username <username> --password <password>` <br> if you omit --username or --password then it will prompt you
+
+This will automatically generate a swagger config `<output_file>` based on the ?describe responses from the PAPI handlers on your node.  Swagger tools can now use this config to create language bindings and documentation.
+
+### To generate PAPI bindings for Python or other languages using the swagger config:
+1. Clone the swagger-codegen repo from https://github.com/swagger-api/swagger-codegen.  You can try the latest version of that code, or if you want to use the last version we've tested as of this writing, it is at commit hash 1939ce8e91f9de4a35ba3d90fd99a28f41c5035c.
+2. Follow the relevant instructions there (in the README.md) to install the codegen java program.  In our case we used "apt-get install maven" to get maven then ran "mvn package" to install codegen.
+3. Copy the `<output_file>` file generated above (or one of the pre-made "example_output.json" files) and "swagger-codegen-config.json" from your isi_sdk root directory to your swagger-codegen root directory.
+4. Run codegen on `<output_file>`.  For example, from your swagger-codegen root directory, use:
+
+`java -jar modules/swagger-codegen-cli/target/swagger-codegen-cli.jar generate -i swagger-config.json -l python -o ./isi_sdk -c swagger-codegen-config.json`
+
+For other languages, substitute the name of the language you want for `python`.  This will create a language bindings library you can install in the `./isi_sdk` subdirectory.
+
+Documentation for the bindings should be generated along with the bindings themselves.  For the Python version, the documentation table of contents is will be in the README.md file in the root of your generated bindings ("./isi_sdk" in the example above).
+
+### Contributing to the isi-sdk OpenAPI config generator
+
+If you have a patch for the config generator scripts that improves the generated swagger config and the bindings that come from it, please submit a pull request to this repository.  We will review it and once the patch is accepted the bindings will be automatically rebuilt and published as a new release.
diff --git a/tests/test_antivirus_policies.py b/tests/test_antivirus_policies.py
@@ -1,15 +1,16 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 antivirusApi = isi_sdk.AntivirusApi(apiClient)
 

diff --git a/tests/test_antivirus_quarantine.py b/tests/test_antivirus_quarantine.py
@@ -1,14 +1,15 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 antivirusApi = isi_sdk.AntivirusApi(apiClient)
 

diff --git a/tests/test_antivirus_scan.py b/tests/test_antivirus_scan.py
@@ -1,14 +1,15 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 antivirusApi = isi_sdk.AntivirusApi(apiClient)
 
@@ -17,10 +18,9 @@
 newScanItem.file = "/ifs/README.txt"
 
 # You'll have to specify an antivirus icap server before this will work.
-# Our isilon icap server is at 10.111.219.215.  POST the following body to
-# /platform/3/antivirus/servers to enable it.
+# POST the following body to /platform/3/antivirus/servers to enable it.
 # {
-#     "url": "icap://10.111.219.215",
+#     "url": "icap://YOUR_ICAP_SERVER_ADDRESS",
 #     "enabled": True
 # }
 

diff --git a/tests/test_antivirus_settings.py b/tests/test_antivirus_settings.py
@@ -1,14 +1,15 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 antivirusApi = isi_sdk.AntivirusApi(apiClient)
 

diff --git a/tests/test_auth_access.py b/tests/test_auth_access.py
@@ -1,14 +1,15 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 authApi = isi_sdk.AuthApi(apiClient)
 

diff --git a/tests/test_auth_groups.py b/tests/test_auth_groups.py
@@ -1,14 +1,15 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 authApi = isi_sdk.AuthApi(apiClient)
 

diff --git a/tests/test_constants.py b/tests/test_constants.py
@@ -0,0 +1,4 @@
+USERNAME = "USERNAME"
+PASSWORD = "PASSWORD"
+VERIFY_SSL = False
+HOST = "https://YOUR_ISILON_CLUSTER_OR_NODE_IP_ADDRESS:8080"
diff --git a/tests/test_protocols_nfs.py b/tests/test_protocols_nfs.py
@@ -1,14 +1,15 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 protocolsApi = isi_sdk.ProtocolsApi(apiClient)
 

diff --git a/tests/test_protocols_smb.py b/tests/test_protocols_smb.py
@@ -1,15 +1,16 @@
 import isi_sdk
 import urllib3
+import test_constants
 
 urllib3.disable_warnings()
 
 # configure username and password
-isi_sdk.configuration.username = "root"
-isi_sdk.configuration.password = "a"
-isi_sdk.configuration.verify_ssl = False
+isi_sdk.configuration.username = test_constants.USERNAME
+isi_sdk.configuration.password = test_constants.PASSWORD
+isi_sdk.configuration.verify_ssl = test_constants.VERIFY_SSL
 
 # configure host
-host = "https://VNODE2294.west.isilon.com:8080"
+host = test_constants.HOST
 apiClient = isi_sdk.ApiClient(host)
 protocolsApi = isi_sdk.ProtocolsApi(apiClient)