Merge pull request #20 from adobe-apiplatform/v2

adobeDan · web-flow · commit 7a7909bffe05 · 2016-12-27T00:12:29.000-08:00
Now that the Github Pages wiki is working, clean up the docs for 2.0b2
diff --git a/README.md b/README.md
@@ -18,50 +18,25 @@ to install from the download.
 
 # Building
 
-1. Clone this repository or download the latest stable release.
+1. Clone this repository or download one of the posted releases.
 2. From the command line, change to the `umapi-client.py` directory.
 3. To install, run the command `python setup.py install`.
-[**NOTE**: You may need admin/root privileges to install new packages in your environment.
-It is recommended that you use `virtualenv` to make a virtual python environment.
-See the [virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
-for more information]
+[**NOTE**: To avoid needing admin/root privileges for the installation
+of needed dependencies,
+it is recommended that you use `virtualenv` (or equivalent)
+to make a virtual python environment.  See the
+[virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
+for more information.
 4. Some of the packages required by this module use encryption, and so may
 require you to do local builds of modules that use SSL.  Typically, this
-will require you to have to `python-dev` module installed (on all platforms),
-and there may be other platform-specific requirements (e.g., on Mac OS X,
-you will need to make sure the latest SSH libraries are on your LIBPATH.)
+will require you to have a python installed that supports compiling
+extensions.
 5. To run tests, use the command `python setup.py test`.
 
-# Getting Started
+# Usage
 
-Before making calls to the User Management API, you must do the following preparation steps:
+Usage documentation, as well as information about how to get client
+credentials for use of the UMAPI, can be found on the
+[umapi-client wiki](https://adobe-apiplatform.github.io/umapi-client.py/),
+whose sources are in the `docs` directory of this repository.
 
-1. Obtain admin access to an Adobe Enterprise Dashboard.
-2. Set up a private/public certificate pair
-3. Create an integration on [Adobe.IO](https://www.adobe.io/)
-
-Step 1 is outside of the scope of this document.
-Please contact your organization's administrator of your Dashbord environment to obtain access.
-Steps 2 and 3 are outlined in the 
-[UMAPI documentation](https://www.adobe.io/products/usermanagement/docs/gettingstarted.html).
-
-Once access is obtained, and an integration is set up, you will need the following configuration items:
-
-1. Organization ID
-2. Tech Account ID
-3. IMS Hostname
-4. IMS Auth Token Endpoint (JWT Endpoint)
-5. API Key
-6. Client Secret
-7. Private Key File (unencrypted form)
-
-All but the last of these will be available on the adobe.io page for your integration.
-The last one you should have on your local disk, and keep secret.
-
-Once these initial steps are taken, and configuration items are identified,
-then you will be able to use this library to make API calls.
-
-# Usage Documentation
-
-The usage documentation may be found on a separate site, which is currently
-under construction.  Please check back on January 2, 2017 for more details.
diff --git a/docs/index.md b/docs/index.md
@@ -13,57 +13,72 @@ of the OSI-approved MIT license.  Copyright (c) 2016 Adobe Systems Incorporated.
 # Installation
 
 You can get this package from PyPI: `pip install umapi-client`.
-Or you can download the posted package from GitHub and use pip
-to install from the download.
+Or you can download the desired release package
+from [GitHub](https://github.com/adobe-apiplatform/umapi-client.py/)
+and use pip to install from the download.
 
 # Building
 
-1. Clone this repository or download the latest stable release.
+1. Clone
+[the Github repository](https://github.com/adobe-apiplatform/umapi-client.py/)
+or download one of
+[the posted releases](https://github.com/adobe-apiplatform/umapi-client.py/releases).
 2. From the command line, change to the `umapi-client.py` directory.
 3. To install, run the command `python setup.py install`.
-[**NOTE**: You may need admin/root privileges to install new packages in your environment.
-It is recommended that you use `virtualenv` to make a virtual python environment.
-See the [virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
-for more information]
+[**NOTE**: To avoid needing admin/root privileges for the installation
+of needed dependencies,
+it is recommended that you use `virtualenv` (or equivalent)
+to make a virtual python environment.  See the
+[virtualenvwrapper documentation](http://virtualenvwrapper.readthedocs.io/en/latest/index.html)
+for more information.
 4. Some of the packages required by this module use encryption, and so may
 require you to do local builds of modules that use SSL.  Typically, this
-will require you to have to `python-dev` module installed (on all platforms),
-and there may be other platform-specific requirements (e.g., on Mac OS X,
-you will need to make sure the latest SSH libraries are on your LIBPATH.)
+will require you to have a python installed that supports compiling
+extensions.
 5. To run tests, use the command `python setup.py test`.
 
 # Getting Started
 
-Before making calls to the User Management API, you must do the following preparation steps:
+Before making calls to the User Management API, you must complete
+the following prepartory steps:
 
 1. Obtain admin access to an Adobe Enterprise Dashboard.
-2. Set up a private/public certificate pair
+2. Set up a private/public key pair
 3. Create an integration on [Adobe.IO](https://www.adobe.io/)
 
 Step 1 is outside of the scope of this document.
-Please contact your organization's administrator of your Dashbord environment to obtain access.
+Please contact an administrator of your organization's
+Dashbord environment to obtain access.
 Steps 2 and 3 are outlined in the
 [UMAPI documentation](https://www.adobe.io/products/usermanagement/docs/gettingstarted.html).
 
-Once access is obtained, and an integration is set up, you will need the following configuration items:
+Once access is obtained, and an integration is set up,
+you will need the following configuration values:
 
 1. Organization ID
 2. Tech Account ID
 3. IMS Hostname
-4. IMS Auth Token Endpoint (JWT Endpoint)
+4. IMS Token Exchange Endpoint (aka JWT Endpoint)
 5. API Key
 6. Client Secret
 7. Private Key File (unencrypted form)
 
-All but the last of these will be available on the adobe.io page for your integration.
+All but the last of these will be available on the
+[adobe.io page for your integration](https://www.adobe.io/console/integrations).
 The last one you should have on your local disk, and keep secret.
 
 Once these initial steps are taken, and configuration items are identified,
 then you will be able to use this library to make API calls.
 
 # Usage Documentation
 
-We are still working on the version 2 usage documentation.
+All new users of the library are highly recommended
+to pick up version 2, and follow the
+[version 2 usage documentation](usage-instructions-v2.html).
 
-You can find the version 1 documentation
-[here](usage-instructions-v1.html).
+Users who have applications running against version 1
+of the library can still use the version 2 implementation,
+but they will need to do some package renames to get access
+to the version 1 library classes.  This is
+outlined in the
+[version 1 usage documentation](usage-instructions-v1.html).
diff --git a/docs/usage-instructions-v1.md b/docs/usage-instructions-v1.md
@@ -1,12 +1,13 @@
-# Usage Instructions
+# V1 Usage Instructions (updated for the v2 release)
 
-The information below was written for version 1 of the client
+The information below was originally written for version 1 of the client
 library.  Since all of the version 1 functionality is now
 available (in a faster, easier-to-use form) from the v2 client
 library, it is recommend that new users start with v2.  However,
 v1 users who have not yet upgraded their applications to the use
-the v2 client can still access this functionality in the
-umapi_client.legacy package, as detailed below.
+the v2 classes can still access v1 classes in the v2 release
+by using the `umapi_client.legacy` package.  The details
+are in the material below.
 
 These instructions presume you have already created your
 [Adobe.IO](https://www.adobe.io/) integration, as described
diff --git a/docs/usage-instructions-v2.md b/docs/usage-instructions-v2.md
@@ -0,0 +1,126 @@
+# V2 Usage Instructions
+
+
+These instructions presume you have already created your
+[Adobe.IO](https://www.adobe.io/) integration, as described
+in the [home page](index.html) of this documentation.
+
+# Getting a Connection
+
+All UMAPI access is predicated on the creation of an authenticated,
+authorized connection to the UMAPI server.  This access always
+happens in the context of a particular integration (as created
+on adobe.io).  So it requires the following details about
+your integration:
+
+1. Organization ID
+2. Tech Account ID
+3. IMS Hostname
+4. IMS Token Exchange Endpoint (aka JWT Endpoint)
+5. API Key
+6. Client Secret
+7. Private Key File (unencrypted form)
+
+Of these, the IMS Hostname and the IMS Token Exchange Endpoint
+are standard across almost all integrations, so they are
+built into the library as defaults and aren't typically needed.
+The Tech Account ID, API Key, and Client Secret are sensitive,
+as is the Private Key File, so a best practice is to keep
+these values in files separate from your application.  The
+Organization ID is not as sensitive, but it's best to keep
+it with the others since it's also needed for authentication.
+
+For example, suppose `config.yaml` is a YAML file
+whose content contains
+the sensitive data (elided here for security):
+
+```yaml
+org_id: '620049..............101@AdobeOrg'
+tech_acct_id: '78E9928............A495DE3@techacct.adobe.com'
+api_key: '265434.............d740ac'
+client_secret: 'cc6.....-....-47b9-....-......ff3725'
+private_key_file: '/path/to/my.secret.key.pem'
+```
+
+and suppose `my.secret.key.pem` contains an unencrypted
+private key
+like this (again, elided for security):
+
+```
+-----BEGIN RSA PRIVATE KEY-----
+MIIEpAIBAAKCAQEAxBc5BFNUP9hdGHSuOzfxoyL2qq2qcqpSexLsefQS9fDZZjCP
+...
+fIOe8cq8F5Vcw6l5NwmW+Lw44hJxKAVRg+j79x6C6+zLblRhm+dHBw==
+-----END RSA PRIVATE KEY-----
+```
+
+Given these two files, you can establish an authenticated,
+authorized connection with code such as the following:
+
+```python
+import yaml # PyYAML from PyPI provides this module
+
+with open(config_file_name, "r") as f:
+    config = yaml.load(f)
+conn = umapi_client.Connection(org_id=config["org_id"],
+                               auth_dict=creds)
+```
+
+The constructor of the Connection object will do all the
+work of contacting the token exchange endpoint and using
+your credentials to obtain an access token, and it will
+remember that access token for use with all your UMAPI
+operations.  It will be called `conn` in the examples
+that follow.
+
+(If you want the details of how access token exchange
+is done by the constructor, see the code or the
+[v1 usage docs](usage-instructions-v1.html).)
+
+# Querying for Users and Groups
+
+Queries for users and groups are implemented by
+classes which allow iterating the results.  These
+iterators pull the results from the server in
+batches of 200 or so, and cache the results locally.
+You can access the full list of results with
+the `all_results` method, and force the query
+to be reloaded and run from the beginning again
+with the `reload` method.
+
+Each fetched user or group is represented as
+a Python dictionary of its attributes.
+
+## Get a List of Users
+
+```python
+users = QueryUsers(conn)
+# print first 5 users
+for i, user in enumerate(users):
+    if i == 5: break
+    print("User %d email: %s" % (i, user["email"]))
+# get a count of all users (finishes the iteration)
+user_count = len(users.all_results())
+```
+
+## Get a List of Groups
+
+This list of groups will contain both user groups and product license
+configuration groups.
+
+```python
+groups = QueryGroups(conn)
+# print all the group details
+for group in groups:
+    print(group)
+# after an hour, see if anything has changed
+time.sleep(3600)
+groups.reload()
+for group in groups:
+    print(group)
+```
+
+# Performing Operations on Users
+
+_...under construction..._
+
