Friday, July 13th, 2012

More v2 Updates

By

In keeping with our promise to continually update the v2 API, we’ve got another batch of v2 enhancements to announce.

Smart Links

You can now create smart links for any file or folder in a Box user’s account. Smart links are direct links to files on Box that you can apply certain permissions to i.e.:

  • Open – anyone
  • Company – only people in the user’s company account
  • Collaborators – only people who are collaborators on the (containing) folder

Smart links are great for applications that need to share files via email and other means but don’t want to deal with directly handling the files. You can read more about what smart links are here and can read the documentation to see how to use them with files and folders.

ETags

Box users frequently collaborate with one another on files. This is a powerful mechanism, but from an API developer’s perspective, it opens up a nasty set of potential race conditions. For example, a user could end up deleting a version of a file after it’s been updated, but without seeing the update because their local copy is stale.

Previously we had an attribute for files labeled “sha1.” This still corresponds to the sha1 of the file but is now named ‘etag’ in the file object. Whenever you delete a file now, you’ll be required to send in that etag as an “If-Match” header. If the version of the file you have matches the one currently stored on Box, the delete will be successful. Otherwise, you’ll receive a 412 Precondition Failed error response.

Non-recursive Folder Deletion

If you’ve ever used a UNIX terminal, you’re familiar with this command:

rm -rf this_full_directory_that_im_deleting

It’s used to delete a directory of folder that has contents inside of it. If you don’t have the optional ‘-rf’, it will fail because you may not want to delete the contents inside of it. We’ve essentially added this same flag to our folder deletion API. Now, when you want to delete a folder with items inside of it, you’ll have to issue a request like this:

DELETE /folders/{folder id}?recursive=true

If you don’t include that extra parameter and the folder has contents inside of it, you’ll receive an error, just like in UNIX.

We’re continually updating v2, but let us know if you have any suggestions or immediate needs

NOTE: The original post indicated that the parameter to delete a non-empty folder was ‘force’. This has since been changed to ‘recursive’.

By

See all of Sean's articles.

  • rei

    I think,
    it’s better to support “*” for If-Match header and the “force” query string should be opitional.

  • talha

    There is no mention of smart link creation/deletion on developers.box.com/docs. How can i create and delete link via the API?

    • http://twitter.com/sean_a_rose Sean Rose

      This is covered in the documentation under ‘Files’ and ‘Folders’. I just added links to the blog post to make it easy to get there.