Thursday, July 12, 2012

We’re dropping API v1 soon


As you may know, SUSE Studio has a RESTful API. The first version (“v1”) was available since the very beginning. Later we added an improved version (“v2”) that allowed access to appliance configuration and new features such as SUSE Gallery.

The API v2 has been available for more than a year and our server logs show that most users already switched to this version. Therefore we decided to drop support for the API v1. We will do this one month from now to give you some time to adapt. On 13 August 2012 we will publish another announcement and remove the old API version.

I still use the API v1 — what should I do?

Don’t panic ;-) The API v2 is mostly an extension (a superset) of v1 so almost all code that works with v1 should work with v2 without any modification. The only important incompatibility between v1 and v2 is that HTTP status error codes returned in certain situations may be different (v2 is more consistent in this regard).

We recommend that you just try pointing your code to the new version and test that everything works. You can do it easily by replacing the http://susestudio.com/api/v1 URL prefix by http://susestudio.com/api/v2.

If you encounter any problems after switching to the new API version, have a look at the API documentation. If that does not help, you can ask on our forum (linked with a mailing list) and we will try to help.

Studio API from Ruby

If you are using Studio API from Ruby, you can make your life easier by using the studio_api gem. It wraps the API into nice objects and works with API v2 smoothly. There are also some other libraries and clients available.

Have ideas for a new version?

We are already thinking about the API v3. If you are a Studio API user, now is the time to have your voice heard and help us determine how the new version should look like! We are mainly interested in hearing answers to the following questions:
  • What do you use the current API for?
  • What features do you miss?
  • Did you find some parts of the API hard to understand or use?
  • Are there any big pain points you’d like to get fixed?
Leave the answers in comments to this blog post. We will use them as a guide when preparing the API v3 design and feature set. Thanks!

1 comment:

  1. I haven't yet get all parts of v2 working yet.

    I'm not able publish or unpublish appliances properly when using the api v2 yet.

    Sometimes I succee to unpublish, but sometimes not. I've not made any changes in my code, so I do not understand why it sometimes works and sometimes not. Just a few minutes ago I first tried without success, and then waited a few minutes and made a new trial, and then it succeeded. I actually do not understand why it didn't worked at my first attempt.

    ReplyDelete

 
© 2013 SUSE