Comments on: API Versioning Tip http://alexking.org/blog/2009/12/13/api-versioning-tip Alex King, Denver Web Developer Thu, 24 May 2012 16:30:11 +0000 hourly 1 http://wordpress.org/?v=3.3.2 By: How to Avoid “API Slamming” and the “API Treadmill” | Open Source Blog http://alexking.org/blog/2009/12/13/api-versioning-tip#comment-120987 How to Avoid “API Slamming” and the “API Treadmill” | Open Source Blog Wed, 06 Jan 2010 18:01:06 +0000 http://alexking.org/?p=3851#comment-120987 [...] are some simple solutions. Alex King shows how to implement versioning with a simple modification to the API endpoint: When people build to your APIs, they need to continue working – even if/when the APIs need [...] [...] are some simple solutions. Alex King shows how to implement versioning with a simple modification to the API endpoint: When people build to your APIs, they need to continue working – even if/when the APIs need [...]

]]> By: How to Avoid “API Slamming” and the “API Treadmill” http://alexking.org/blog/2009/12/13/api-versioning-tip#comment-120898 How to Avoid “API Slamming” and the “API Treadmill” Wed, 06 Jan 2010 07:27:35 +0000 http://alexking.org/?p=3851#comment-120898 [...] are some simple solutions. Alex King shows how to implement versioning with a simple modification to the API endpoint: When people build to your APIs, they need to continue working - even if/when the APIs need to [...] [...] are some simple solutions. Alex King shows how to implement versioning with a simple modification to the API endpoint: When people build to your APIs, they need to continue working – even if/when the APIs need to [...]

]]> By: Alex http://alexking.org/blog/2009/12/13/api-versioning-tip#comment-117630 Alex Mon, 14 Dec 2009 15:11:40 +0000 http://alexking.org/?p=3851#comment-117630 <blockquote>One additional problem this approach can bring is getting clients that use the APIs to transition to updated versions.</blockquote> That's an excellent point - I was thinking about this as well. I'm considering adding a couple of properties to the return values of the API - something along the lines of: - current API version - API version deprecation date Ideally the old API versions could live forever, but I also realize that isn't always realistic.

One additional problem this approach can bring is getting clients that use the APIs to transition to updated versions.

That’s an excellent point – I was thinking about this as well. I’m considering adding a couple of properties to the return values of the API – something along the lines of:

- current API version
- API version deprecation date

Ideally the old API versions could live forever, but I also realize that isn’t always realistic.

]]> By: Joseph Scott http://alexking.org/blog/2009/12/13/api-versioning-tip#comment-117629 Joseph Scott Mon, 14 Dec 2009 15:03:52 +0000 http://alexking.org/?p=3851#comment-117629 Agreed, I like the idea of having the version number right in the URL. One additional problem this approach can bring is getting clients that use the APIs to transition to updated versions. Not a deal breaker, but something that should be considered. Agreed, I like the idea of having the version number right in the URL. One additional problem this approach can bring is getting clients that use the APIs to transition to updated versions. Not a deal breaker, but something that should be considered.

]]> By: links for 2009-12-13 « burningCat http://alexking.org/blog/2009/12/13/api-versioning-tip#comment-117582 links for 2009-12-13 « burningCat Mon, 14 Dec 2009 02:03:00 +0000 http://alexking.org/?p=3851#comment-117582 [...] API Versioning Tip [...] [...] API Versioning Tip [...]

]]> By: Alex http://alexking.org/blog/2009/12/13/api-versioning-tip#comment-117580 Alex Mon, 14 Dec 2009 02:02:18 +0000 http://alexking.org/?p=3851#comment-117580 Blocking access to .svn directories is trivial: <code>RedirectMatch 404 /\.svn(/|$)</code> and the benefits of managing your web sites with live checkouts are too numerous to detail here. Temporary branches should be made in the branches/ dir, not the tags/ dir. If this is a sticking point to someone, an <code>svn export</code> would accomplish the same thing in this case. Blocking access to .svn directories is trivial:

RedirectMatch 404 /\.svn(/|$)

and the benefits of managing your web sites with live checkouts are too numerous to detail here.

Temporary branches should be made in the branches/ dir, not the tags/ dir.

If this is a sticking point to someone, an svn export would accomplish the same thing in this case.

]]> By: gslin http://alexking.org/blog/2009/12/13/api-versioning-tip#comment-117562 gslin Sun, 13 Dec 2009 21:01:52 +0000 http://alexking.org/?p=3851#comment-117562 If you use svn, don't put ".svn" directory into webroot, a better way is to use deploy utility to spread your code, don't use "svn co" in server side directly. Usually keep .svn away from webroot will enhance security. If you insist to put .svn into webroot for some reasons. Avoid to use .htaccess to deny outside access as only ACL. Also remember to use another username & password to do checkout. This can avoid username and password leaking when .svn be accessed. It's because when people trying to upgrade from Apache to lighttpd or nginx, they *often* forget to add configuration to deny .svn directory. Putting all tags directory into webroot is not a good habit, I think. Sometimes you will use VCS to create a temporily branch to do some work, which causes security risk. A better approach might be to use hg/git, they only put .hg/.git into root directory of working repository. And remember to use deploy utility, most utility can set filter to avoid some directories and files be deployed. Back to the origin subject, delicious API and Amazon Web Services API seems good examples. The first one use "v1" as version path, and the later one use release date /2008xxxx/, fixed version number /1.0/, and /latest/ to keep different version (and different level) of API. I believe this already an acceptable solution. If you use svn, don’t put “.svn” directory into webroot, a better way is to use deploy utility to spread your code, don’t use “svn co” in server side directly. Usually keep .svn away from webroot will enhance security.

If you insist to put .svn into webroot for some reasons. Avoid to use .htaccess to deny outside access as only ACL. Also remember to use another username & password to do checkout. This can avoid username and password leaking when .svn be accessed. It’s because when people trying to upgrade from Apache to lighttpd or nginx, they *often* forget to add configuration to deny .svn directory.

Putting all tags directory into webroot is not a good habit, I think. Sometimes you will use VCS to create a temporily branch to do some work, which causes security risk.

A better approach might be to use hg/git, they only put .hg/.git into root directory of working repository. And remember to use deploy utility, most utility can set filter to avoid some directories and files be deployed.

Back to the origin subject, delicious API and Amazon Web Services API seems good examples. The first one use “v1″ as version path, and the later one use release date /2008xxxx/, fixed version number /1.0/, and /latest/ to keep different version (and different level) of API. I believe this already an acceptable solution.

]]>