Monday, September 10th, 2012

V2 API updates keep rolling…

By , Senior Platform Product Manager

We’re very excited about the new V2 API, as well as some of the fixes that we’re doing to the V1 API along the way. As part of that work, we have a handful of changes that we have either rolled out recently, or will be rolling out soon.

Please keep in mind that the V2 API is still in Beta. There are some important changes coming in authentication that will mean developers that are using V2 API will have to change how they authenticate their users. Plan it into your integration project (just as you’re already planning on moving off the V1 APIs anyway, right?!).

Okay, enough about bookkeeping and planning. Back to the exciting stuff: new features.

Expiring tags:

We’ve rolled out 2 new security feature for all our API callers around ticket expiration. We now expire the temporary ticket a bit more aggressively. Now, as soon as you successfully get an authentication_token, we expire the ticket. We also tightened up the expiration timer to 10 minutes max, so you can’t wait a long time between getting the ticket for your user, directing them at the Box authentication flow, and getting the auth token. This was asked by several of our developer partners. It aligns more with the OAuth standards. More very exciting news about authentication changes for V2 coming soon. Be watching for the blog post.

FTP admin control

We’ve also decided to roll out Admin control for FTP. We did this by making FTP officially a “Box Application.” Under the covers FTP has been a Box application now for over a year, but we didn’t expose it in the app marketplace, nor did we show it to Admins as something they could enable or disable for their users. Well, the admins asked for more control, and we’ve delivered: Admins can now go into their App management console and enable or disable FTP for their users, just like they can any other Box app.

Collaborators and Collaborations

V2 API adds the /collaborations endpoint, making it possible to get or modify the list of collaborators on a folder. This is a V2 API only, so V1 API callers will need to move over the V2 in order to use it. The GET operations allows you to see and change the security settings for the collaboration. PUT allows you to add or modify collaborations from a folder. All this is available via the /collaborations sub-endpoint. See the documentation for more details about how to use this new API. (Docs may not post until a few days after this blog post).

Enhanced error codes:

We’ve paid some special attention to the errors returned for all kinds of problems… over your quota, no longer have permission on the file. See the updated section in our docs about errors This includes a new special deprecated error code (http 428), that will tell you when the way you are calling one of our APIs is going away. We’ve actually used this already on a couple of the early V2 features as we realized the way we were doing things didn’t actually quite fit in with our overall design.

POST /folders
Here’s where we used that new 428 error code to move from an early V2 API implementation to a better V2 API before we GA the V2. For creating a new folder, instead of doing a POST to ../folders/ to specify that you wanted to create a new folder under the parent folder. We’ve changed this to be a POST to ../folders with the body specifying what the parent folder id is. It’s a subtle change, but if you already implemented against the former, we’re returning a 428 warning to you for about a month, when we’ll start returning an error.

That’s it for now. More V2 API endpoints coming soon. Watch this blog space for more details and more API announcements.

By ,

Senior Platform Product Manager

See all of Peter's articles.