[Iplant-api-dev] Agave API Scheduled Maintenance

[Rion Dooley]

The iPlant Agave Developer APIs will undergo a maintenance period from 11pm CST on Friday, March 5 to 1am CST on Saturday, March 6 to upgrade the API servers and to address an outstanding issue with versioning in the APIs. During this maintenance period, any jobs or data transfers you started prior to the update will continue to run and all registered notifications will still be sent.  First things first,

1. YOU SHOULD KNOW THAT THIS UPDATE WILL INTRODUCE A CHANGE TO THE AGAVE URLS.

The short explanation is that this will be less confusing and impact you less when we release versions 2.1, 2.2, etc.

The longer explanation is that currently all APIs have a 2.0 version built into their URL (ie. https://agave.iplantc.org/apps/2.0). This version number will be changed from 2.0 to v2 (ie. https://agave.iplantc.org/apps/v2). We are making this change now for three reasons. First, so the version accurately describes the version of the API as a whole. At the time we released Agave, we wanted to accurately reflect that we were on the second major release of our API, but due to limitations in our routing mechanism, we could not set the version to 2 or v2, thus we went with the closest thing, 2.0. Since then we have fixed the problem and we can use a more appropriate version number. Second, as we continue to improve the API and introduce additional functionality in subsequent updates, 2.0 will no longer reflect the actual version of the API. In order to avoid confusion, we wanted to make this change sooner rather than later. Third, many of you are early on in the integration process or just getting start. This change will be a minor issue for the majority of you. For those users who have already completed their integration, a simple search and replace will more than likely be all the updating you need to do.

2. YOU WILL NEED TO UPDATE YOUR API KEYS

Due to the above change, and some modifications to our auth server, your API keys will be invalidated after the maintenance period concludes. We know that getting API keys was a huge pain for many of you, and we’re very aware of that as an area we need to improve upon. The good new is that we have improved this process and it should be much, much easier for everyone from now on. Keep reading to find out how.

3. THE REST OF THIS EMAIL MAKES THE FIRST TWO CHANGES TOTALLY WORTH IT

Several of the things you expressed to us over and over again were concerns and frustrations centered around understanding OAuth, getting API keys, and porting apps from Foundation to Agave. During this maintenance period we will address these issues in several ways. First, we will add the following new content, tools, and services.

All your favorite (public) apps
Probably the most asked question from users coming over from Foundation was, “where are the apps?” This week we begin to answer that question by porting over 70 public apps from Foundation to Agave. This covers all public applications still active and run since June 1, 2013.

Access to the Open Science Grid
Another concern many users have had over the last year has been centered around queue wait times on public systems. While we can’t avoid the queues on large, shared systems like Stampede and Lonestar, we are always looking for opportunities to leverage other systems to increase our overall capacity. This week we will add the Open Science Grid as a public system, providing additional compute capacity for the entire iPlant community.

Help migrating your apps
While the addition of Foundation's public apps covers much of the overall usage from Foundation, it may not include the app you currently use. So, for users needing to migrate their private apps from Foundation to Agave, we are adding a new conversion tool to the Agave developer’s website. This tool will convert your Foundation app descriptions into a format Agave will accept. While your previous wrapper scripts will still work just as they did before, you can safely comment out or remove any iget and iput commands since Agave will automatically handle all data staging for you. You will find the new app at http://agaveapi.co/app-converter after the maintenance period.

Easier client registration
Many of you pointed out (passionately!) the frustration you felt just trying to get your API keys. You told us there were too many steps, too much to figure out, and too many places to go. We completely agree, which is why we are so excited to announce the release of a new client registration service. This service gives you a simple REST API to create and manage your api keys. No more visiting the API Store and manually subscribing to each API. A single call to the service will return a shiny new set of API keys ready to use on any of the APIs. You can find out more about the client registration service after the maintenance period at http://agaveapi.co/client-registration/ and view the REST API documentation at http://agaveapi.co/live-docs/.


Additionally, several developer tools will be updated to support the changes:

Updated command line interface (CLI)
We couldn’t be happier with how many of you are using the CLI as both a learning and productivity tool. This week we will be updated the CLI with a couple minor bug fixes and the addition of three new scripts to help you create and managing manage your API keys.

Updated client libraries
It’s been great seeing the community contribute to the development of client libraries for languages such as R and Perl. We’ve been busy as well, updating our Java, PHP, and Python client libraries. This week’s update will address the authentication and serialization issues some users were having.

Updated documentation
With the new client registration service and updated apps, it makes sense that we would naturally update our documentation. Expect to see changes in the sections on authentication, a new page on getting your API keys, and the new app converter tool mentioned above.

Samples and examples
Lastly, we know nothing makes learning a new API better than working examples. That’s why we’re updating the agave-samples project to provide better tutorials based on concrete examples using public apps and systems. We’ll also be adding code samples for each of our client libraries to help you get up and running with those.


The net result of this update will be a more accessible API with better documentation and tooling that empowers you to start using the API in a much shorter time. Our goal is to help the newest user get from ground zero to moving data and running jobs in 5 minutes or less. Our hope is that you will keep sending us feedback and suggestions to help us reach our goal.

If you have any questions or concerns, please contact support at iplantcollaborative.org<mailto:support at iplantcollaborative.org>.

Sincerely,
Rion




--
Rion




-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.iplantcollaborative.org/pipermail/iplant-api-dev/attachments/20140304/d4d28b98/attachment.html