Skip to content

Commit

Permalink
Merge pull request #2 from TACC-Cloud/doc_changes
Browse files Browse the repository at this point in the history 
Doc changes
  • Loading branch information
@joestubbs
joestubbs committed Dec 5, 2018
2 parents 07b4f7a + 37a279b commit 4522a49
Show file tree
Hide file tree
Showing 32 changed files with 389 additions and 421 deletions.
14 changes: 7 additions & 7 deletions docs/agave/guides/apps/app-sharing-apps.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -494,25 +494,25 @@ To publish an app, make a PUT request on the app resource. In this example, we p
],
"_links": {
"self": {
"href": "https://public.agaveapi.co/apps/v2/wc-osg-1.00u1"
"href": "https://api.tacc.utexas.edu/apps/v2/wc-osg-1.00u1"
},
"executionSystem": {
"href": "https://public.agaveapi.co/systems/v2/condor.opensciencegrid.org"
"href": "https://api.tacc.utexas.edu/systems/v2/condor.opensciencegrid.org"
},
"storageSystem": {
"href": "https://public.agaveapi.co/systems/v2/public.storage.agave"
"href": "https://api.tacc.utexas.edu/systems/v2/public.storage.agave"
},
"history": {
"href": "https://public.agaveapi.co/apps/v2/wc-osg-1.00u1/history"
"href": "https://api.tacc.utexas.edu/apps/v2/wc-osg-1.00u1/history"
},
"metadata": {
"href": "https://public.agaveapi.co/meta/v2/data/?q=%7B%22associationIds%22%3A%228734854070765284890-242ac116-0001-005%22%7D"
"href": "https://api.tacc.utexas.edu/meta/v2/data/?q=%7B%22associationIds%22%3A%228734854070765284890-242ac116-0001-005%22%7D"
},
"owner": {
"href": "https://public.agaveapi.co/profiles/v2/nryan"
"href": "https://papi.tacc.utexas.edu/profiles/v2/nryan"
},
"permissions": {
"href": "https://public.agaveapi.co/apps/v2/wc-osg-1.00u1/pems"
"href": "https://api.tacc.utexas.edu/apps/v2/wc-osg-1.00u1/pems"
}
}
}
Expand Down
36 changes: 18 additions & 18 deletions docs/agave/guides/authorization/introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ The method is suitable for long-running applications in which the user logs in o

.. code-block:: http
https://public.tenants.agaveapi.co/authorize/?client_id=gTgp...SV8a&response_type=code&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=PRODUCTION&state=866
https://api.tacc.utexas.edu/authorize/?client_id=gTgp...SV8a&response_type=code&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback&scope=PRODUCTION&state=866
The authorization process starts with your application sending a request to the Agave authorization service. (The reason your application sends this request can vary: it may be a step in the initialization of your application or in response to some user action, like a button click.) The request is sent to the /authorize endpoint of the Authorization service:

Expand Down Expand Up @@ -200,7 +200,7 @@ After the user accepts (or denies) your request, the Agave Authorization service
</tr>
<tr>
<td>access_token </td>
<td>An access token that can be provided in subsequent calls, for example to <a href="https://public.agaveapi.co/profiles/v2/me?pretty=true">Agave Profiles API</a>. </td>
<td>An access token that can be provided in subsequent calls, for example to <a href="https://api.tacc.utexas.edu/profiles/v2/me?pretty=true">Agave Profiles API</a>. </td>
</tr>
<tr>
<td>token_type </td>
Expand Down Expand Up @@ -252,7 +252,7 @@ If the user has denied access, there will be no access token and the final URL w

.. code-block:: bash
POST https://public.tenants.agaveapi.co/token
POST https://api.tacc.utexas.edu/token
When the authorization code has been received, you will need to exchange it with an access token by making a POST request to the Agave Authorization service, this time to its ``/token`` endpoint. The body of this POST request must contain the following parameters:

Expand Down Expand Up @@ -281,7 +281,7 @@ When the authorization code has been received, you will need to exchange it with
-d "client_id=gTgp...SV8a"
-d "client_secret=hZ_z3f...BOD6"
-d "redirect_uri=https%3A%2F%2Fwww.foo.com%2Fauth"
https://public.tenants.agaveapi.co/token
https://api.tacc.utexas.edu/token
..
Expand Down Expand Up @@ -350,7 +350,7 @@ On success, the response from the Agave Authorization service has the status cod
.. code-block:: bash
curl -H "Authorization: Bearer a742...12d2"
https://public.tenants.agaveapi.co/profiles/v2/me?pretty=true&naked=true
https://api.tacc.utexas.edu/profiles/v2/me?pretty=true&naked=true
..
Expand Down Expand Up @@ -382,7 +382,7 @@ Once you have a valid access token, you can include it in ``Authorization`` head
curl -sku "Authorization: Basic Qt3c...Rm1y="
-d grant_type=refresh_token
-d refresh_token=d77c...Sacf
https://public.tenants.agaveapi.co/token
https://api.tacc.utexas.edu/token
..
Expand All @@ -403,7 +403,7 @@ The request is sent to the token endpoint of the Agave Authorization service:

.. code-block::
POST https://public.tenants.agaveapi.co/token
POST https://api.tacc.utexas.edu/token
The body of this POST request must contain the following parameters:

Expand Down Expand Up @@ -444,7 +444,7 @@ Implicit grant flow is for clients that are implemented entirely using JavaScrip

.. code-block:: json
https://public.tenants.agaveapi.co/authorize?client_id=gTgp...SV8a&redirect_uri=http:%2F%2Fexample.com%2Fcallback&scope=PRODUCTION&response_type=token&state=867
https://api.tacc.utexas.edu/authorize?client_id=gTgp...SV8a&redirect_uri=http:%2F%2Fexample.com%2Fcallback&scope=PRODUCTION&response_type=token&state=867
The flow starts off with your application redirecting the user to the ``/authorize`` endpoint of the Authorization service. The request will include parameters in the query string:

Expand Down Expand Up @@ -529,7 +529,7 @@ After the user grants (or denies) access, the Agave Authorization service redire
</tr>
<tr>
<td>access_token </td>
<td>An access token that can be provided in subsequent calls, for example to <a href="https://public.agaveapi.co/profiles/v2/me?pretty=true">Agave Profiles API</a>. </td>
<td>An access token that can be provided in subsequent calls, for example to <a href="https://api.tacc.utexas.edu/profiles/v2/me?pretty=true">Agave Profiles API</a>. </td>
</tr>
<tr>
<td>token_type </td>
Expand Down Expand Up @@ -585,7 +585,7 @@ If the user has denied access, there will be no access token and the final URL w

.. code-block:: bash
curl -H "Authorization: Bearer 61e6...Mc96" https://public.tenants.agaveapi.co/profiles/v2/me?pretty=true
curl -H "Authorization: Bearer 61e6...Mc96" https://api.tacc.utexas.edu/profiles/v2/me?pretty=true
..
Expand Down Expand Up @@ -626,7 +626,7 @@ The method is suitable for scenarios where there is a high degree of trust betwe
-d username=rjohnson
-d password=password
-d scope=PRODUCTION
https://public.tenants.agaveapi.co/token
https://api.tacc.utexas.edu/token
..
Expand Down Expand Up @@ -696,7 +696,7 @@ If the user has not accepted your request or an error has occurred, the response
.. code-block:: bash
curl -H "Authorization: Bearer 3Dsr...pv21"
https://public.tenants.agaveapi.co/profiles/v2/me?pretty=true
https://api.tacc.utexas.edu/profiles/v2/me?pretty=true
..
Expand Down Expand Up @@ -729,7 +729,7 @@ The access token allows you to make requests to any of the Agave REST APIs on be
-d grant_type=refresh_token
-d refresh_token=dyVa...MqR0
-d scope=PRODUCTION
https://public.tenants.agaveapi.co/token
https://api.tacc.utexas.edu/token
..
Expand Down Expand Up @@ -787,7 +787,7 @@ The method is suitable for authenticating your requests to the Agave REST API. T
curl -sku "Authorization: Basic Qt3c...Rm1y="
-d grant_type=client_credentials
-d scope=PRODUCTION
https://public.tenants.agaveapi.co/token
https://api.tacc.utexas.edu/token
..
Expand Down Expand Up @@ -829,7 +829,7 @@ The request is sent to the ``/token`` endpoint of the Agave Authentication servi
.. code-block:: bash
curl -H "Authorization: Bearer 61e6...Mc96"
https://public.tenants.agaveapi.co/profiles/v2/me
https://api.tacc.utexas.edu/profiles/v2/me
..
Expand All @@ -840,7 +840,7 @@ The request is sent to the ``/token`` endpoint of the Agave Authentication servi
{
"email": "nryan@mlb.com",
"firstName" : "Nolan",
"firstName" : "Nolan",
"lastName" : "Ryan",
"position" : "null",
"institution" : "Houston Astros",
Expand All @@ -854,10 +854,10 @@ The request is sent to the ``/token`` endpoint of the Agave Authentication servi
"gender" : "M",
"_links" : {
"self" : {
"href" : "https://public.tenants.agaveapi.co/profiles/v2/nryan"
"href" : "https://api.tacc.utexas.edu/profiles/v2/nryan"
},
"users" : {
"href" : "https://public.tenants.agaveapi.co/profiles/v2/nryan/users"
"href" : "https://api.tacc.utexas.edu/profiles/v2/nryan/users"
}
}
}
Expand Down
40 changes: 20 additions & 20 deletions docs/agave/guides/clients/introduction.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@
Clients and API Keys
--------------------

By now you already have a user account. Your user account identifies you to the web applications you interact with. A username and password is sufficient for interacting with an application because the application has a user interface, so it knows that the authenticated user is the same one interacting with it. The Agave API does not have a user interface, so simply providing it a username and password is not sufficient. Agave needs to know both the user on whose behalf it is acting as well as the client application that is making the call. Whereas every person has a single user account, they may leverage multiple services to do their daily work. They may start out using :raw-html-m2r:`<a href="https://togo.agaveapi.co/" title="iPlant Discovery Environment" target="_blank">Agave ToGo</a>` to kick of an analysis, then switch to :raw-html-m2r:`<a href="https://edublog/" title="MyPlant" target="_blank">MyPlant</a>` to discuss some results, then receive an Slack notice that new data has been shared with them, click a :raw-html-m2r:`<a href="#postits" title="Pre-Authenticated URL Shortening with PostIts">PostIt</a>` link that allows them to download the data directly to their desktop, edit the file locally, and save it in a local folder that syncs with their iPlant :raw-html-m2r:`<a href="http://www.iplantcollaborative.org/discover/data-store" title="iPlant Data Store" target="_blank">cloud storage</a>` in the background.
By now you already have a user account. Your user account identifies you to the web applications you interact with. A username and password is sufficient for interacting with an application because the application has a user interface, so it knows that the authenticated user is the same one interacting with it. The Agave API does not have a user interface, so simply providing it a username and password is not sufficient. Agave needs to know both the user on whose behalf it is acting as well as the client application that is making the call. Whereas every person has a single user account, they may leverage multiple services to do their daily work.

In each of the above interactions, the user is the same, but the context with which they interact with the Agave is different. Further, the above interactions all involved client applications developed by the same organization. The situation is further complicated when one or more 3rd party client applications are used to leverage the infrastructure. Agave needs to track both the users and client applications with whom it interacts. It does this through the issuance of API keys.
In different types of Agave interactions, the user is the same, but the context with which they interact with the Agave is different. Further, the different Agave interactions all involve client applications developed by the same organization. The situation is further complicated when one or more 3rd party client applications are used to leverage the infrastructure. Agave needs to track both the users and client applications with whom it interacts. It does this through the issuance of API keys.

Agave uses :raw-html-m2r:`<a href="http://oauth.net/2" title="OAuth2" target="_blank">OAuth2</a>` to authenticate users and make authorization decisions about what APIs client applications have permission to access. A discussion of OAuth2 is out of the context of this tutorial. You can read more about it on the :raw-html-m2r:`<a href="http://oauth.net/2" title="OAuth2" target="_blank">OAuth2</a>` website or from the websites of any of the many other service providers using it today. In this section, we will walk you through getting your API keys so we can stay focused on learning how to interact with the Agave's APIs.

Expand All @@ -25,7 +25,7 @@ In order to interact with any of the Agave APIs, you will need to first get a se

.. code-block:: shell
curl -sku "$API_USERNAME:$API_PASSWORD" -X POST -d "clientName=my_cli_app" -d "description=Client app used for scripting up cool stuff" https://public.tenants.agaveapi.co/clients/v2
curl -sku "$API_USERNAME:$API_PASSWORD" -X POST -d "clientName=my_cli_app" -d "description=Client app used for scripting up cool stuff" https://api.tacc.utexas.edu/clients/v2
.. code-block:: plaintext
Expand All @@ -49,13 +49,13 @@ In order to interact with any of the Agave APIs, you will need to first get a se
"tier":"Unlimited",
"_links":{
"self":{
"href":"https://public.tenants.agaveapi.co/clients/v2/my_cli_app"
"href":"https://api.tacc.utexas.edu/clients/v2/my_cli_app"
},
"subscriber":{
"href":"https://public.tenants.agaveapi.coprofiles/v2/nryan"
"href":"https://api.tacc.utexas.edu/profiles/v2/nryan"
},
"subscriptions":{
"href":"https://public.tenants.agaveapi.co/clients/v2/my_cli_app/subscriptions/"
"href":"https://api.tacc.utexas.edu/clients/v2/my_cli_app/subscriptions/"
}
}
}
Expand All @@ -74,7 +74,7 @@ Listing your existing client applications

.. code-block:: shell
curl -sku "$API_USERNAME:$API_PASSWORD" https://public.tenants.agaveapi.co/clients/v2
curl -sku "$API_USERNAME:$API_PASSWORD" https://api.tacc.utexas.edu/clients/v2
.. code-block:: plaintext
Expand All @@ -96,13 +96,13 @@ Listing your existing client applications
"tier":"Unlimited",
"_links":{
"self":{
"href":"https://public.tenants.agaveapi.co/clients/v2/DefaultApplication"
"href":"https://api.tacc.utexas.edu/clients/v2/DefaultApplication"
},
"subscriber":{
"href":"https://public.tenants.agaveapi.coprofiles/v2/nryan"
"href":"https://api.tacc.utexas.edu/profiles/v2/nryan"
},
"subscriptions":{
"href":"https://public.tenants.agaveapi.co/clients/v2/DefaultApplication/subscriptions/"
"href":"https://api.tacc.utexas.edu/clients/v2/DefaultApplication/subscriptions/"
}
}
},
Expand All @@ -114,13 +114,13 @@ Listing your existing client applications
"tier":"Unlimited",
"_links":{
"self":{
"href":"https://public.tenants.agaveapi.co/clients/v2/my_cli_app"
"href":"https://api.tacc.utexas.edu/clients/v2/my_cli_app"
},
"subscriber":{
"href":"https://public.tenants.agaveapi.coprofiles/v2/nryan"
"href":"https://api.tacc.utexas.edu/profiles/v2/nryan"
},
"subscriptions":{
"href":"https://public.tenants.agaveapi.co/clients/v2/my_cli_app/subscriptions/"
"href":"https://api.tacc.utexas.edu/clients/v2/my_cli_app/subscriptions/"
}
}
}
Expand All @@ -145,7 +145,7 @@ Deleting client registrations
**Show curl**
.. code-block:: shell
curl -sku "$API_USERNAME:$API_PASSWORD" -X DELETE https://public.tenants.agaveapi.co/clients/v2/my_cli_app
curl -sku "$API_USERNAME:$API_PASSWORD" -X DELETE https://api.tacc.utexas.edu/clients/v2/my_cli_app
.. code-block:: plaintext
Expand All @@ -169,7 +169,7 @@ Listing current subscriptions
**Show curl**
.. code-block:: shell
curl -sku "$API_USERNAME:$API_PASSWORD" https://public.tenants.agaveapi.co/clients/v2/my_cli_app/subscriptions
curl -sku "$API_USERNAME:$API_PASSWORD" https://api.tacc.utexas.edu/clients/v2/my_cli_app/subscriptions
.. code-block:: plaintext
Expand All @@ -192,13 +192,13 @@ Listing current subscriptions
"tier":"Unlimited",
"_links":{
"api":{
"href":"https://public.tenants.agaveapi.co/apps/v2/"
"href":"https://api.tacc.utexas.edu/apps/v2/"
},
"client":{
"href":"https://public.tenants.agaveapi.co/clients/v2/systest_test_client"
"href":"https://api.tacc.utexas.edu/clients/v2/systest_test_client"
},
"self":{
"href":"https://public.tenants.agaveapi.co/clients/v2/systest_test_client/subscriptions/"
"href":"https://api.tacc.utexas.edu/clients/v2/systest_test_client/subscriptions/"
}
}
},
Expand Down Expand Up @@ -237,7 +237,7 @@ Updating client subscriptions
**Show curl**
.. code-block:: shell
curl -sku "$API_USERNAME:$API_PASSWORD" -X POST -d "name=transforms" https://public.tenants.agaveapi.co/clients/v2/my_cli_app/subscriptions
curl -sku "$API_USERNAME:$API_PASSWORD" -X POST -d "name=transforms" https://api.tacc.utexas.edu/clients/v2/my_cli_app/subscriptions
.. code-block:: plaintext
Expand All @@ -256,7 +256,7 @@ Updating client subscriptions
**Show curl**
.. code-block:: shell
curl -sku "$API_USERNAME:$API_PASSWORD" -X POST -d "name=*" https://public.tenants.agaveapi.co/clients/v2/my_cli_app/subscriptions
curl -sku "$API_USERNAME:$API_PASSWORD" -X POST -d "name=*" https://api.tacc.utexas.edu/clients/v2/my_cli_app/subscriptions
.. code-block:: plaintext
Expand Down

0 comments on commit 4522a49

Please sign in to comment.